Emarsys - Real-Time Behavioral Data Streams

This guide will walk you through configuring Fullstory's Anywhere: Activation to trigger real-time events to SAP Emarsys. This connection allows you to use rich behavioral data from Fullstory to trigger marketing automations, such as emails, SMS, and in-app messages, within the Emarsys platform.

Prerequisites

Before you begin, ensure you have:

• An active Fullstory account with access to Anywhere: Activation.
• An active SAP Emarsys account with administrative access to manage API credentials, external events, and contact fields.
• A clear understanding of the user identifier you will use to link users between Fullstory and Emarsys (e.g., email address, cookie id).

Step 1: Configure Events and API Credentials in SAP Emarsys

First, you need to set up the endpoint in Emarsys that Fullstory will send data to. This involves creating an "External Event" to get a unique ID and generating API credentials for secure access.

Part A: Create an External Event

Each Stream from Fullstory will trigger a specific event in Emarsys, and each event needs its own unique ID.  

1. In your Emarsys account, navigate to Management > External Events.
2. Click Create a new external event.
3. Give the event a descriptive name that reflects the user action you're tracking, such as "Product Tile Engagement".
4. After creating the event, Emarsys will generate an External Event ID (e.g., 2078). Copy this ID and save it for later; you will need it for the Fullstory configuration.

Part B: Create API Credentials

Next, create dedicated API credentials for Fullstory to use for authentication.

1. Navigate to Management > Security Settings and select the API Credentials tab.
2. Click to create a new API credential, selecting OpenID Connect (OAuth2) as the mechanism.
3. Assign a name to the credential (e.g., "Fullstory Integration").
4. You must assign the correct permissions. Search for and add the External Event > Trigger permission.
5. After saving, Emarsys will provide three crucial pieces of information: a Client ID, a Client Secret, and a Token Endpoint. Copy and securely save all three values.
   • Note: Emarsys notes that a new API key may take up to five minutes to become active.

Step 2: Configure the Real-Time Stream in Fullstory

With the Event ID and API credentials from Emarsys, you can now configure the Stream in Fullstory.

1. In Fullstory, navigate to Settings > Anywhere > Activation.
2. Click Create Stream. (See Streams for complete documentation).
3. Give the Stream a descriptive name, such as "Emarsys - Product Click Trigger".

Part A: Configure the Connection and Endpoint URL

In the Destination section:

1. Destination type:  Choose HTTP Endpoint.
2. API Endpoint URL: Construct the endpoint URL for the Emarsys event trigger API.
   • Use the following format, replacing {event_id} with the External Event ID you created in Step 1:
     
     (POST) https://api.emarsys.net/api/v3/event/{event_id}/trigger
3. Connection: First, set up the authentication.
   • In the Connection section, click + Create connection.
   • Enter a name for the connection, such as "Emarsys Fullstory Stream".
   • For Authentication type, select OAuth2 client credentials.
   • Copying the Token Endpoint, Client ID, and Client Secret from Emarsys, paste into the corresponding Fullstory fields: Access token URL, Client ID, Client secret.
   • Save the connection.

Part B: Define the Trigger Event

1. In the Definition section, specify which Fullstory event should trigger this Stream. For example, you can trigger it on every click of an element named "Product Tile".
   • Note: See the Streams documentation for guidance on setting up your Stream's Definition, including considerations about Activation Quota.

Part C: Field Mapping

Fullstory simplifies payload creation for Emarsys with a pre-built template. 

1. In the Field Mapping section, under Destination template, select Emarsys
2. This template provides two required fields: key_id and external_id.
   • key_id: This field tells Emarsys which user attribute to use for matching (e.g., email, customer ID). You must find the corresponding ID in Emarsys by navigating to Management > Field Editor. For example, the standard "Email" field has an ID of 3. Enter this numeric ID into the key_id value field.
   • external_id: This is the value of the identifier. Map this to the corresponding Fullstory user variable (e.g., select User > Email from the variable picker).
3. You can pass additional event properties by clicking the plus button (+) next to a current property. The template will automatically nest them under a data object in the final payload.

Step 3: Test and Monitor the Integration

Your Fullstory Stream configuration is almost complete.

1. Send a Test from Fullstory: In the Send Test section, click the Send Test button to send a sample payload to Emarsys. Make sure the user you are testing with exists as a contact in Emarsys.
2. Monitor in Emarsys:
   • In Emarsys, navigate to Management > Event Monitoring. This dashboard will display incoming events in near real-time.
   • Set the time filter to Last Hour to see recent activity.
   • Once a test is successful, you will see the event appear on the monitoring page. You can click on an event to inspect its payload and confirm all data was received correctly.

3. Click Save to finalize and activate the Stream. 

Advanced Use Cases

Fullstory's streaming capabilities are flexible. Beyond triggering events, you can also use Streams to call other Emarsys API endpoints to achieve different outcomes:

• Update User Fields: You can configure a Stream to update a contact field in Emarsys. For example, if a user performs a series of actions that qualifies them as a "High Value User," a Stream could update a custom field on their Emarsys contact record.
• Sync Anonymous Users: For anonymous visitors, you can sync the Fullstory Device ID into a custom field in Emarsys via their web SDK. This allows you to stream events for unknown users and associate the activity with their contact record once they identify themselves.