Skip to main content

Integration checklist

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

Planning stage​

important

Communication with our API endpoints should happen only from a backend environment to avoid exposing sensitive authentication credentials to end users.

1. Choosing an SDK​

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

2. Understanding the two APIs​

Talon.One offers two 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.

3. Creating your campaigns​

Create at least one campaign containing one or more rules to test your integration.

For more information, see the campaign overview page in our Product docs.

4. 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 set them within your session update or customer profile update requests.

See:

5. Importing or migrating data​

Depending on the tools that you use in addition to Talon.One, you can import or migrate your data into Talon.One to create highly targeted promotional campaigns:

Implementation stage​

1. Handling customer sessions​

important

Sessions are a key concept. Read Customer sessions.

A session represents a customer's cart. In general, integrating with Talon.One consists in sending customer session updates requests to Talon.One.

Ensure you apply the following good practices:

  • Session ID: Use an immutable ID.
  • Session state: Update the state of your session depending on your order workflow.

A session is usually created in the open state (new order) or closed state (legacy order).

  • open: The session can be modified as many times as needed.

  • closed: The session cannot be modified anymore.

    note

    A closed session can be reopened with the Reopen customer session endpoint.

    Also:

    • The session data is fed into the campaign analytics.
    • Potential coupons are redeemed.

  • cancelled: The session had an issue or the closed or partially returned states are not valid anymore. Also:

    • The session data is removed from the campaign analytics.
    • Coupons redeemed in the session are usable again.
    • Coupons created in the session are not deleted.
    • The impact of the session's effects on campaign budgets is reverted, except for coupon creations.
    • Rollback effects undo previous effects triggered when you closed or opened the session.
    • Attribute value updates are not rolled back.

  • partially returned: One or more cart items have been returned and the closed state is not valid anymore. Also:

    • Rollback effects undo previous effects triggered when you closed or opened the session.
    • The impact of the session's effects on campaign budgets is reverted.
    • Attribute value updates are not rolled back.
Examples
  • open: The customer is adding items, referral codes or coupons to their shopping cart.
  • closed: The customer has completed the payment step (or any last step) of the order workflow.
  • cancelled: The customer requested a full refund or the payment failed.
  • partially returned: The customer returned some of the items and expects the corresponding refund.

2. Implementing with performance in mind​

Do more with one call: The Update customer session and Update customer profile endpoints offer 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 or Update customer profile endpoint but do not want the request to modify your Application, set the runRuleEngine and dry parameters to true to send a dry request and get faster response times. You will still see the returned effects but there will be no change to your Application.

Use a single event for a single customer action: When implementing customer actions, consider that each event represents a single occurrence of a customer action related to a customer session or customer profile. To avoid receiving too many 409 responses, ensure that the customer action does not trigger multiple events in parallel.

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 signed in. After an anonymous customer becomes known, replace the profileId in the session with the new one.

See:

4. Parsing the returned effects​

Part of the customer session update response is the effects array. This object contains additional information regarding custom attribute values for all triggered campaigns and the reason why potential effects failed.

See the JSON structure of all effects.

You can also create your own effects, if needed.

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 monitor them. They are available in the Integration API reference docs for each endpoint.

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

Optional steps​

1. Whitelisting IP addresses​

After you have created your campaigns, Talon.One can whitelist your IP addresses. Only the addresses you send to us are able to send API requests or to sign in to the Campaign Manager.

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

2. 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:

3. Dealing with Talon.One API URL changes​

As part of the implementation stage, 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/v2/ or mycompany.europe-west1.talon.one/v2/.

We suggest that you ensure your integration supports URL changes.