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 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 rule engine.

Sending updates to Talon.One

To get started, include the Talon.One SDK for your language in your backend code, and configured 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. The example below represents a change to the order total:

talon = TalonOne::Integration::Client.new :endpoint => 'https://mycompany.talon.one',
                                          :application_id => 15025,
                                          :application_key => '41d3f05e76fd667b'

# The first argument is an arbitrary object that will be passed to registered effect handlers.
# The second argument is a session ID.
talon.update_customer_session context, "order-1234", {
  # The profile ID identifies the current customer
  :profileId => "customer-42",

  # The total value of the current order
  :total => BigDecimal("35.37").to_f,
}

var TalonOne = require('talon-one/integration')

var applicationId = 15025
var applicationKey = '41d3f05e76fd667b'

var talon = new TalonOne.IntegrationClient('https://mycompany.talon.one', applicationId, applicationKey)

// The first argument is an arbitrary object that will be passed to registered effect handlers.
// The second argument is a session ID.
talon.updateCustomerSession(context, "order-1234", {
  // The profile ID identifies the current customer
  profileId: "customer-42",

  // The total value of the current order
  total: 35.37,
})

from talon_one import integration

application_id = 15025
application_key = "41d3f05e76fd667b"

talon = integration.Client("https://mycompany.talon.one", application_id, application_key)

# The first argument is a session ID.
talon.update_customer_profile("order-1234", {
  # The profile ID identifies the current customer
  "profileId": "customer-42",

  # The total value of the current order
  "total": 35.37
})

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"
  }
}

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

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:

talon.update_customer_profile "customer-1234", {
  :attributes => {
    "Name" => "Anthony Ray",
    "ShippingCity" => "Seattle",
    "ShippingRegion" => "Washington"
  }
}

talon.updateCustomerProfile("customer-1234", {
  attributes: {
    Name: "Anthony Ray",
    ShippingCity: "Seattle",
    ShippingRegion: "Washington"
  }
})

talon.update_customer_profile("customer-1234", {
  "attributes": {
    "Name": "Anthony Ray",
    "ShippingCity": "Seattle",
    "ShippingRegion": "Washington"
  }
})

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 a service that wraps the API client, performing calls and processing effects:

class TalonService
  def initialize(context, client)
    @context = context
    @client = client
  end

  def update_customer_session(id, payload)
    @client.update_customer_session(id, payload).tap do |response|
      handle_effects(response)
    end
  end

  def update_customer_profile(id, payload)
    @client.update_customer_profile(id, payload).tap do |response|
      handle_effects(response)
    end
  end

  def track_event(session_id, type, attributes)
    @client.track_event(session_id, type, attributes).tap do |response|
      handle_effects(response)
    end
  end

  protected

  # Here is where your app-specific effect handling would go
  def handle_effects(response)
    response.effects.each do |effect|
      case effect.name
      when "setDiscount"
        @context.current_order.set_discount(*effect.args)
      end
    end
  end
end

References:

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