Skip to main content

Integration checklist

Every integration is unique but keep in mind the following points.

Planning stage#

1. Choosing an SDK#

Talon.One offers SDKs for various language. Use them to integrate with Talon.One via the Integration API.

2. Understanding the 2 APIs#

Talon.One offers 2 APIs: the Integration API and the Management API. They differ in their authentication methods and their purpose. For most use cases, the Integration API is the only API you need.

See:

3. Creating your promotions#

Some promotion types like: free item campaigns, referral programs, coupon campaigns or loyalty programs require additional effect handling or some additional attributes.

Ensure you know which attributes and effects are involved.

For more information, see Campaign Library.

4. Whitelisting IP addresses#

Talon.One can whitelist your IP addresses. Only the addresses you send to us will be able to send API requests or to log in to the Campaign Manager.

To whitelist IPs, send the list to support@talon.one.

5. Using the Talon.One proxy#

Since Talon.One is an API-based product, the whole communication is based on requests and responses. To simplify and speed up this interaction, we recommend using a proxy to create a persistent connection to your deployment.

You can create your own solution or you can use the Talon.One proxy and create a persistent connection to our services.

See:

6. Creating your attributes#

Attributes are an important part of the Talon.One integration.

Attributes allow you to build any kind of promotion based on product properties. For example, they can represent the weight of an item, the segment of a user, a payment method, etc.

Create them in the Campaign Manager and use them within your session or profile-update requests.

important

Ensure that each attribute you send is already created in the Campaign Manager.

See:

Implementation stage#

1. Knowing which effects to implement#

The main part of the integration is the implementation of the returned effects.

Talon.One provides a wide palette of effects. Ensure to cover the ones your marketing team will use in production.

See:

2. Handling customer session statuses#

In general, the integration with Talon.One consists in sending customer session updates.

A session has a status: open, closed, or canceled.

When you want to create a new session, pass status: open in the request.

During the customer's journey, the open status won't change until the customer reaches the final step, like the checkout step. At this point, pass status: closed.

Closing a session also feeds the session data into the campaign analytics and a coupon in the session will be redeemed.

important

A closed session can't be opened again.

You can set the status to canceled of open or closed sessions. This resets the analytics data and any coupon redemption related to the session.

Performance tips

Do more with one call: The Update customer session endpoint offers a responseContent property that you can use to save API calls. For example, you can use this property to retrieve the customer profile information without having to use another endpoint.

Reduce response time: When you query the Update customer session endpoint but do not require to run rules, set the runRuleEngine parameter to false to skip Rule Engine execution and get even faster response times.

3. Handling profiles and sessions#

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 known, replace the profileId in the session with the new one.

See the integration tutorial.

4. 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.

5. Dealing with error responses#

Talon.One receives a bad request, it returns an error code. Ensure that your system is able to catch them or even monitor them.

Typical examples of bad requests are when the integration sends an unknown session attribute or a wrongly formatted coupon attribute.

6. Dealing with Talon.One API URL changes#

Talon.One offers the possibility to move your cluster to a preferred Google Cloud location.

Moving a cluster will change the API URL, such as mycompany.talon.one/v1/ or mycompany.europe-west1.talon.one/v1/.

We suggest that you ensure your integration supports URL changes.