Skip to main content

Creating a custom effect to award minutes

Talon.One offers a set of effects via its Integration API that you can use to get data to the integration layer. But sometimes, the data that they return might not be what you require.

In this case, a custom effect allows you communicate any data from Talon.One to the integration layer in the form of a structured effect.

Like any other effect, custom effects are returned when you call the Update customer session when a rule is valid.

note
  • This tutorial assumes you have a basic understanding of effects, attributes and rules.
  • If you do not want to return the data as an effect, you can use a webhook instead.

Understanding the context​

Let's imagine we run a company that rents bicycles by the minute and we want to reward customers with free minutes when they use a coupon code.

To do this, we must create a rule with the following logic:

  • If the coupon is valid then send the awarded number of minutes to the integration layer.

No core effects provides information about awarded minutes, so let's create a custom effect to cover our use-case.

Creating a custom effect​

Let's create our Award minutes custom effect. It will appear in the Rule Builder as a new effect type.

  1. In the bottom-left of the Campaign Manager, click Account > Tools > Custom Effects.
  2. Click Create Custom Effect.
  3. In Scope, select Cart (Session).
  4. In API name, type Award_minutes.
  5. In Rule Builder name, type Award minutes is the name of the effect. It appears in the effects section when we create a rule.
  6. In Applications, select your Application.

Let's add parameters to our effect.

Adding parameters​

Parameters represent the data of the effect that can be edited from the Rule Builder's UI.

In our case, we need a number of minutes and the ID of the customer involved. To do this we only need one parameter because:

  • The number of minutes should be customizable from the Campaign Manager's Rule Builder.
  • The profile ID is set by the integration layer without user input when we create sessions so we do not need a parameter.

Let's create the parameter:

  1. In Param type, select number.
  2. In Param name, let's type a user-friendly name such as minutes. This will appear in the Rule Builder.
  3. In Param Description, let's type The number of minutes awarded.. This will appear in the Rule Builder.

Creating the payload​

We've defined the parameter for the users of the Rule Builder, now let's define the payload for our integration layer.

We want the effect to contain:

  • The number of minutes defined with a parameter.
  • The profile ID represented by the profile's IntegrationId built-in attribute.

To do this, we use the following payload:

{
  "awardedMinutes": "${$minutes}",
  "customerID": "${$Profile.IntegrationId}"
}

Click Create and our effect is ready for use.

Creating a rule​

In a standard campaign, let's create the rule to award minutes.

  1. Open the Rule Builder in your campaign and create a rule:
    1. Condition: Coupon code is valid
    2. Effect: Award minutes
  2. Edit the value of the minutes parameter.
  3. Save and enable the Campaign.

When the rule triggers, the integration layer receives the following example payload:

Update customer session response
{
    "createdCoupons": [],
    "createdReferrals": [],
    "effects": [
        {
            "campaignId": 3882,
            "rulesetId": 12230,
            "ruleIndex": 0,
            "ruleName": "Award minutes",
            "effectType": "acceptCoupon",
            "triggeredByCoupon": 3308130,
            "props": {
                "value": "SUMMER-2021"
            }
        },
        {
            "campaignId": 3882,
            "rulesetId": 12230,
            "effectType": "customEffect",
            "triggeredByCoupon": 3308130,
            "props": {
                "effectId": 1,
                "name": "Award minutes",
                "payload": {
                    "awardedMinutes": "30",
                    "ProfileId": "111"
                }
            }
        }
    ],
    "ruleFailureReasons": [],
    "triggeredCampaigns": [
        {
           ...
        }
    ]
}

We can now parse the response to extract the data we needed. Notice we get 2 effects, the usual core acceptCoupon effect when a coupon is valid and a customEffect with the data we need: the awarded minutes and the customer ID.