Tutorials and Guides
Be sure to consider the following points during each stage of your integration.
Which SDK do you want to use (or self-made solution)
Integration API vs Management API
We are offering two main APIs: the Integration API and the Management API. They differ in their different authentication methods and their different purposes. For most use cases the Integration API is the only API you will need. The API references can be found here: Integration API / Management API
What kind of promotions do you want to run?
Since some promotion types like: "free item" campaigns, referral programs, coupon campaigns or loyalty programs require additional effect handling or some additional attributes, it's very helpful to make sure from the beginning, which promotions you want to run through Talon.One. More information can be found here: Campaign Library
Whitelist IP addresses
We offer the possibility to whitelist your IP addresses which means, that only the addresses you send us will be able to send requests to our API endpoints or log in to our UI. Feel free to send us the list to firstname.lastname@example.org.
Since Talon.One is an API based product the whole communication to our system will be made by sending requests and receiving their responses. To simplify and speed up this interaction we recommend using a proxy which is creating a persistent connection to your deployment. While you are free to create your own solution we already offer a proxy that will allow you to create a persistent connection to our services.
Attributes are a very important part of the Talon.One integration. Attributes allow you to build any kind of promotion based on properties (e.g. weight of an item, segment of a user, payment method of the session) your product is already using. Once you created a new attribute in the developer section of the Talon.One UI you will be able to send it within your session- or profile-update request. More information about how to create attributes can be found here: Creating Attributes
⚠️ Please make sure that each attribute you are sending has already been created in the UI otherwise you would - due to security reasons - receive an error.
Which type of effects do you want to implement?
The main part of the integration is the implementation of the returned effects. Since we are offering a wide palette of them, you should make sure to cover the ones your marketing team will use in production. All currently active effects can be found here: Integration API effects
Session status handling
In most of the cases integration Talon.One is about sending "customer session updates". Since a session is, besides other attributes, defined by the status it's important to handle it correctly. Once you want to create a new session you need to pass "status: open" within the request. During the customer's journey the status "open" will be the same until the customer reaches the final step (e.g. the checkout) where you need to pass "status: closed". Closing a session will also feed the session data into the campaign analytics and a coupon in the session will be redeemed. You should keep in mind, that a closed session cannot be opened again. The third status "canceled" can be set either on "open" or "closed" sessions and will reset the analytics data and any coupon redemption related to the session.
⚠️ A closed session can never be opened again.
Sessions and profiles
A Session can be connected to a profile by passing the integration-id of the customer as the value of the "profileId" attribute. We highly recommend to always pass a profileId even if the customer is anonymous or not logged in. Once an anonymous customer becomes a known one you can simply replace the "profileId" in the session with the new one.
Parsing the Meta-Response
Part of the "customer session update" response is the "meta" object. This object contains additional information regarding "custom attribute values for all triggered campaigns" and most important the reason why a coupon code was rejected.
Dealing with error responses
Whenever there is a flawed request (e.g. Sending us an unknown session attribute or sending a false formatted coupon attribute) we are returning an error code. Please make sure that your system is able to catch them and in the best case you should be able to monitor them.
Talon.One API URL
We offer the possibility to move your cluster to a preferred Google cloud location. Moving a cluster will change the API URL (e.g. test.talon.one/v1/ > test.europe-west1.talon.one/v1/). We suggest making sure that the URL can be easily changed in your integration.
If you’d like a member of our support team to respond to you, please send a note to email@example.com