About custom events

This article defines what a custom event is. It then describes how to submit custom events to the SessionM platform, how to view them in the activity log, and how to use them to build campaign-based behavioral rules and segment audiences. The article concludes with a scenario that show how you can use custom events in a SessionM campaign.

At-a-glance

Custom events

Member action (other than a purchase) relevant to your loyalty program. Examples include downloading an app or writing a review.

Any action that the client application can detect and submit to the SessionM platform.

Must be in the format required by SessionM.

Viewable in customer profile activity log.

Used to define rules-based behaviors for campaigns and to build audiences.

• Custom events

• Submitting custom events to the SessionM platform

• Viewing custom events in the activity log

• Using custom events in behavioral rules in campaigns

• Using custom events for audience segmentation

• Scenario: Browse but does not buy

Custom events

A custom event represents a single occurrence of a specific member action other than a purchase that you want to track in your loyalty program. (Purchases in SessionM are referred to as transactions.) For example, an event could be enrolling in a loyalty program or completing a survey. The only requirement is that the custom event is the format required by SessionM. Once submitted to SessionM, custom events are available for use in defining behaviors in campaigns and in building audiences.

A custom event can be simple or complex.

Simple custom event

A simple custom event has a:

• name

• transaction ID used to identify the event.

• quantity that indicates how many times the event was performed

• timestamp in ISO format that indicates when the event occurred. If the client application does not include a timestamp, SessionM evaluates the event as if it occurred at the time SessionM processes the event.

{
    "events": {
        "profile_complete": {
            "transaction_id": "1234",
            "qty": "1",
            "date": "{{time_stamp}}"
        }
    }
}

Complex custom event

Like a simple custom event, the complex custom event has a name, transaction ID, quantity and date. In addition, the complex custom event has a context object. The context object is a set of key-value pairs that enables you to provide more information about the event to the SessionM platform. Note that the key value pairs in the context object must have a flat structure; they cannot be nested.

{
    "events": {
        "contest_entry": {
            "transaction_id": "1234",
            "qty": "1",
            "date": "{{time_stamp}}",
            "context": {
                "contest": "camera_giveaway"
            }
        }
    }
}

NOTE: To use complex custom events, the process_events_as_purchases Rails variable must be set to FALSE. Contact your SessionM customer care team for guidance.

Submitting custom events to the SessionM platform

Client applications use the "events" endpoint to submit the payload in the format expected by SessionM, as shown below:

POST /priv/v1/apps/:api_key/external/users/:external_id/events

See.SessionM Event APIs for more information.

Viewing custom events in the activity log

You can view when custom events have occurred in the activity log in the customer profile for a loyal program member.

The following image shows activity log where the "payment_card_added" event took place on April 5.

See About customer profiles for more information.

Configuring the activity log to display custom events

The activity log does not display custom events by default. You must configure the activity log to include custom events in its display. See Configure event stream with Timeline Series Config tool for a step-by-step procedure for configuring the activity log to display custom events.

Using custom events in behavioral rules in campaigns

You can use custom events to build behavioral rules in promotional campaigns. You define a behavior that has an "Engages in Custom Event" rule. You then specify the name of a specific custom event that has been submitted to the SessionM platform as a restriction to the "Engages in Custom Event" rule.

The following image shows how you use the "profile_complete" custom event in a behavior.

Note that you can assign an outcome for any custom event submitted to the SessionM platform. In the image above, an award of ten points is granted to members who have completed a profile.

With a simple custom event, the behavioral rule is evaluated on the presence or absence of the that event in the SessionM platform. With a complex custom event, you can build a more sophisticated rule that involves properties from the context. See Scenario: Browse but does not buy for an example of using a complex custom event.

Using custom events for audience segmentation

Custom events are stored in the "campaign_events" table in the SessionM data lake. Using the Query tool in Audience Composer module, you can build audiences based on the members' event history. For example, you could build an audience of all members who have completed the "posted_review" event (where a member has posted a review on social media) in the past month. You could then send an offer to these members as a reward for completing the review.

SELECT  
    distinct user_id
FROM
    campaign_event
WHERE
    date(time_stamp) >= current_date - interval '30' day
    and name = "posted_review"
    and data_date >= current_date - interval '35' day
;

See What is a SessionM audience? for more information on the Audience Composer module.

Scenario: Browse but does not buy

Here's the scenario: Koalla Clothing is running a back-to-school sale on its web site. If a loyalty program member browses an item but does not buy it, Koalla wants to text them a reminder to complete the purchase. The text, however, is only sent if the item is in stock and has not already been marked down. Let's take a look at how this works in SessionM.

Submitting the "Browse but does not buy" custom event payload

When a member browses but does not buy an item, the Koalla site submits a SessionM event API with the following payload:

{
    "events": {
        "product_view": {
            "transaction_id": "1234",
            "qty": "1",
            "date": "{{time_stamp}}",
            "name": "product_view",
            "context": {
                "activity_event_name": "product_view",
                "page_id": "sale",
                "product_id": "UO-685382-000",
                "product_sku": "726574",
                "product_markdown_state": "NONE",
                "category_id": "clothes-dresses",
                "customer_channel": "ios",
                "customer_id": "427706",
                "product_backinstock": "1"
            }
        }
    }
}

Note that this is a complex custom event because it includes a context section that provides additional properties describing the event.

Building "Browse but does not buy" behavioral rule

Koalla defines and launches a promotional campaign that "listens" for the "Buy but do not browse" custom event to occur and then triggers the text message

The following image shows how the "Browse but does not buy" behavioral rule is defined in the SessionM platform. Notice the use of the context fields to further refine that rule to in-stock items that have not been marked down.