Integrating Talon.One

This guide walks through the general process of integrating Talon.One's Campaign Manager & Rule Engine with any business.

Regardless of the type of campaign you wish to run, you will need to supply the Talon.One's Rule Engine with data about your customer's activities so that it can make decisions (and trigger effects) based on them. Your integration code will need to take care of two responsibilities:

1. Sending session and profile updates to Talon.One.
2. Processing effects returned by the Talon.One's Rule Engine.

Sending updates to Talon.One

To get started, include the Talon.One SDK for your language in your backend code, and configure it with your application ID and application key.

Customer Sessions

In Talon.One a customer order/transaction is represented by a CustomerSession, which is created/updated using the updateCustomerSession API operation. Note: a Talon.One Customer Session has nothing to do with a server session. It is upto the API client to decide when (and if) they should be closed.

You will want to send one of these update requests whenever your customer performs an activity that you want the rule engine to respond to, such as adding an item to their cart, or entering a coupon code. In the below example customer enters a coupon code to get a discount on their cart items:

import talon_one
from talon_one.rest import ApiException

configuration = talon_one.Configuration()
configuration.host = "https://mycompany.talon.one"

configuration.api_key["Authorization"] = "07308ea1c16e1181c4bdc0c29c9c0b72152a73e5"
configuration.api_key_prefix["Authorization"] = "ApiKey-v1"

# Integration API example to send a session update
integration_api = talon_one.IntegrationApi(talon_one.ApiClient(configuration))

# Preparing a NewCustomerSessionV2 object
customer_session = talon_one.NewCustomerSessionV2(
  "SDKCOUPON"
)
customer_session.cart_items = [
  talon_one.CartItem("Red Spring Blouse", "rdbs-1111", 1, 350, "Shirts"),
  talon_one.CartItem("Denim Trousers", "dtr-2222", 1, 250, "Trousers"),
]
customer_session.coupon_codes = [
  "test_UHBT5CI"
]
integration_request = talon_one.IntegrationRequest(
  customer_session,
)

# Create/update a customer session using `update_customer_session_v2` function
 api_response = integration_api.update_customer_session_v2("session_v2_SDK", integration_request)

Updates to a session are merged, so as long as you use the same session identifier, you don't need to repeat redundant information. This next example represents a customer entering shipping information:

talon.update_customer_session("order-1234", {
  "attributes": {
    "ShippingCity": "Seattle",
    "ShippingRegion": "Washington"
  }
})

The possible attributes are configured in the Developer Settings for your account. There you can select from a large number of predefined attributes, or even create completely custom attributes just by selecting a name and a type. In the Rule Builder section of Campaign Manager, you or your marketing managers can then create sophisticated rules matching these attributes.

Customer Profiles

The next level of integration concerns attributes of your customers themselves. To work with address, device, location or shopping history data, you should bundle these and send them to Talon.One in the form of a CustomerProfile. A customer profile is the "owner" of a session and may have many sessions over it's lifetime, effectively describing your customer's business history with you. Profiles are created & updated using the updateCustomerProfile API operation, which functions similarly to updateCustomerSession above:

customer_profile_id = 'customer-1234'

body = talon_one.NewCustomerProfile({
  'Name': "Anthony Ray",
  'ShippingCity': "Seattle",
  'ShippingRegion': "Washington"
})
api_response = integration_api.update_customer_profile_v2(customer_profile_id, body)

CustomerProfiles can be customized with industry specific attributes in the same fashion as CustomerSessions.

References:

• Data Model
• Attributes

Process Effects

Now that you have a working data pipeline into the Talon.One rule engine, you will want to work with the results (called Effects) of your campaign rules, so that your coupon validations, referral or loyalty programs actually do something useful.

For every session or profile update that you send, Talon.One immediately runs all applicable rules and returns the resulting effects in the HTTP API response. Exactly how you process these effects depends on the SDK you are using: you can register effect handlers, or loop through the "effects" array in the response. The below example shows how you can loop through the "effects" array to check if effect type is a setdiscount and sets the discount value if the condition matches:

# Parsing the returned effects list, please consult https://developers.talon.one/Integration-API/handling-effects for the full list of effects and their corresponding properties
    for effect in api_response.effects:
        if effect.effect_type == "setDiscount":
            # Initiating right props instance according to the effect type
            setDiscountProps = integration_api.api_client.deserialize_model(effect.props, talon_one.SetDiscountEffectProps)

            # Access the specific effect's properties
            print("Set a discount '{name}' of {value}".format
                    (name = setDiscountProps.name
                    ,value = setDiscountProps.value))
        elif effect.effect_type == "rejectCoupon":
           rejectCouponEffectProps = integration_api.api_client.deserialize_model(effect.props, talon_one.RejectCouponEffectProps)

            # Work with AcceptCouponEffectProps' properties
            # ...

References:

• Handling Effects contains a complete reference to the effects that your integration must handle to operate correctly