The Optimove server-side API allows you to send events that do not necessarily result directly from user activity in your website or mobile app. For example, changes in a player’s deposit balance or changes to a customer’s loyalty point balance.

Once properly implemented, your server can report nearly any event or user action to Optimove for storage, real-time analysis and campaign activation.

The following parameter types are available for use in the events:

String – A series of alphanumeric characters of up to 255 characters in length, using any encoding
Number – Any numeric value, whether an integer or a value containing a decimal point
Boolean – Either true or false (not a string)

Important notes:

Event and parameter names are case sensitive.
Events and parameters use snake_case as a naming convention. Separate each word with one underscore character (_) and no spaces. (e.g., checkout_completed).
All monetary values must be reported in the same currency defined in your Optimove instance (e.g., if your instance is based on US dollars, all monetary event values must be reported in US dollars). Optimove will not perform currency conversions.
If your Optimove instance supports multiple languages, all event parameters must use a single default language. This is required in order to maintain a unified set of events.

Enabling Optimove’s Server-Side API

Optimove’s Customer Solution Engineer Team will help you define the use cases to report to Optimove, allowing you to pre-configure your desired server-side events and their parameters before you begin reporting them to Optimove.

In order to implement server-side events:

Contact your Customer Success Manager (CSM) or your other Optimove point of contact to request implementation of the server-side API in your Optimove site.
Define the server-side events and parameters to be supported and configure them in your Optimove site, in conjunction with the Customer Solution Engineer Team. You can follow this guide for further information on how to configure events and parameters.
After configuring the events, Optimove’s Customer Solution Engineer Team will send you:
1. Optimove API Endpoint to be used for each API request.
2. Optimove Tenant ID to use for each API request
3. Real-Time Triggers (formerly Track & Trigger) token
4. Event keys for each server-side event you can report using the API
5. The parameter keys and data types that can be included with each configured event
Report events to Optimove by calling the API from your server-side code.

Reporting Server-Side Events (API V2)

Overview

Starting in Version 2 of the API (noted by the v2 path prefix), events sent to Optimove server side API should be sent using HMAC authorization.

Please make sure to follow the below steps after receiving your endpoint, token and tenant ID from Optimove’s Customer Solution Engineer Team:

Add the following headers to each request sent:
1. X-Optimove-Signature-Content
  1. This header is an HMAC-SHA256 of the request body.
  2. The HMAC’s key is your Real-Time Triggers (formerly Track & Trigger) token that you receive from your Optimove Point of Contact.
  3. For example, to create this header in JS/TS use the following code snippet:
```
function generateHash(trackAndTriggerToken: string, rawTextBody: Buffer | string) {
	return crypto.createHmac('sha256', trackAndTriggerToken)
		.update(Buffer.from(JSON.stringify(rawTextBody), 'utf-8'))
		.digest('hex');
}
```
2. X-Optimove-Signature-Version = 1

Error Codes

If either header is missing, respond with a 422 Unprocessable Entity status and no HTTP body.
If the signature is invalid, respond with a 401 Unauthorized status and no HTTP body.

Server-side events must be reported using the following structure

Body

Schema

{
    "tenant": int,
    "event": "string",
    "context": {
        "event_device_type": "string",
        "event_native_mobile":boolean,
        "event_platform": "string",
        "event_os": "string",
        "<param_key>": datatype according to configuration
    },
    "visitor": "string",
    "customer": "string",
    "timestamp": "DateTime"
}

Sample Request

{
    "tenant": 123,
    "event": "order",
    "context": {
        "event_device_type": "Web",
        "event_native_mobile": false,
        "event_platform": "iOS",
        "event_os": "iOS 13.5.0",
        "order_amount": 1000
    },
    "visitor": "5f6318f9dd72a705",
    "customer": "943437",
    "timestamp": "2020-05-26T07:40:45.495Z"
}

Headers

Schema

Content-Type = application/json
X-Optimove-Signature-Version = 1
X-Optimove-Signature-Content = <HMAC-SHA256 of the body>

Example

Given the example request body above, and a Real-Time Triggers (formerly Track & Trigger) token of '12356789', these are the expected headers (most notable, the X-Optimove-Signature-Content)

Content-Type = application/json
X-Optimove-Signature-Version = 1
X-Optimove-Signature-Content = a56995ec9935105c3261677dd7a0e19f1ce66ad594da9326cffbe6e74ac019e6

Important notes:

For events that are generated by a visitor/customer, the request must contain either a VisitorID or a CustomerID.
If sending a customerID, the ID must match the Customer ID (CID) you are sending Optimove on a daily basis. This CID is used to connect the data received via events to customers within your Optimove customer database.
Event and parameter names are case-sensitive.
The event received by Optimove, must match it’s configuration details within the platform.
"event_device_type", "event_native_mobile", "event_platform", "event_os" paravmeters are not mandatory and can be used for tracking or triggering purposes.
"<param_key>" represents a custom parameter. By default, these parameters are set to be non-mandatory. An event can include up to 50 different custom parameters. In the Sample Request above, “order_amount” is a custom parameter.
"timestamp" is not required and if not sent as part of the request will be generated by the system upon receival.
All monetary values must be reported in the same currency defined in your Optimove instance (e.g., if your instance is based on US dollars, all monetary event values must be reported in dollars). Optimove will not perform currency conversions.
If your Optimove instance supports multiple languages, all event parameters must use a single default language. This is required in order to maintain a unified set of events.
If you’re currently using Optimove’s Server Side API with no authorization and would like to add this method please contact your CSM or Optimove’s Customer Solution Engineer Team

Sequential Events

Triggered campaigns are activated when a visitor or a customer sets off a Trigger. Triggers are built, within the Optimove platform, with events. Triggers can be defined as activated either by events that arrive in a specific sequence or events that arrive in any given order.

For Triggers that are activated by events that arrive in a specific sequence, it is important that Optimove receives the relevant events in same order as defined within the Trigger.

In order to ensure the correct order of arrival, you may send the relevant events as part of the same request, within an array, like so:

[
    {
        "tenant": int,
        "event": "<event_key>",
        "context": {
            "event_device_type": "Mobile/Web",
            "event_native_mobile": true, // false,
            "event_platform": "<platform Ex. iOS/Android>",
            "event_os": "<operating system Ex. iOS 13.5.0>",
            "<param_key>": "<param_value>"
        },
        "visitor": "<visitorid>",
        "customer": "<customerid>",
        "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
    },
    {
        "tenant": int,
        "event": "<event_key>",
        "context": {
            "event_device_type": "Mobile/Web",
            "event_native_mobile": true, // false,
            "event_platform": "<platform Ex. iOS/Android>",
            "event_os": "<operating system Ex. iOS 13.5.0>",
            "<param_key>": "<param_value>"
        },
        "visitor": "<visitorid>",
        "customer": "<customerid>",
        "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
    }
]

The events will then be received by Optimove in the order in which they appear in the array.

Important note:

A max of 10 events can be part of the same request and should be used when sending events for the same customer/visitor.

Pre-Defined Events

Optimove has a set of pre-defined events that, once received, instruct the Optimove system to perform actions that are key to ensure correct identity resolution and campaign execution:

Set email
Set user ID
Set page visit

Pre-defined events notes:

Pre-defined events are preconfigured within your Optimove instance. There is no need to manually configure pre-defined events.
Pre-defined events cannot contain any additional custom parameters.

Set Email Event

This pre-defined event attaches an email address to a visitor or a customer entity in real time. After reporting this event, a visitor / customer may be targeted by an email execution channel.

Event structure:

{
    "tenant": int,
    "event": "set_email_event",
    "context": {
        "event_device_type": "Mobile/Web",
        "event_native_mobile": true, // false,
        "event_platform": "<platform Ex. iOS/Android>",
        "event_os": "<operating system Ex. iOS 13.5.0>",
        "email": "<email>"
    },
    "visitor": "<visitorid>",
    "customer": "<customerid>",
    "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
}

Set Email event notes:

For set email events, "email" is a mandatory parameter and should be a valid email address.

Set User ID Event

Optimove distinguishes between unknown website visitors, website visitors that have converted today, and customers.

Unknown website visitors are entities that are allocated a temporary ID, in the case of server-side events, by a system external to Optimove (visitor ID management by Optimove is supported only by implementing Optimove’s SDK).

Customers are entities that are allocated a customer ID by a system external to Optimove. The bulk of the information related to these customers is received through the daily ETL process.

Visitors that have converted today are entities that are in transition between the two states above. Information on these entities has not yet been received through the daily ETL, however, a customer ID has been allocated.

This pre-defined event notifies the Optimove system that a visitor has been converted into a customer. These customers can be targeted with a Triggered Campaign that is set on the “Converted Today” Target Group on the day of conversion, or any Customer Target Groups in the following days.

Event structure:

{
    "tenant": int,
    "event": "set_user_id_event",
    "context": {
        "event_device_type": "Mobile/Web",
        "event_native_mobile": true, // false,
        "event_platform": "<platform Ex. iOS/Android>",
        "event_os": "<operating system Ex. iOS 13.5.0>",
        "userId": "<customerid>"
    },
    "visitor": "<visitorid>",
    "customer": "<customerid>",
    "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
}

Set User ID event notes:

For set user ID events, "userId" is a mandatory parameter.
Upon receiving this event, Optimove will update the original visitorID with an updated visitorID that is composed out of the first 16 digits of the SHA-1 of the customerID.
Upon visitor conversion, in order to ensure that events generated while in a visitor state are correctly attached to the customer, a "set_user_id_event" must be sent with the correct mapping between the visitor and customer IDs.

Set Page Visit

This pre-defined event notifies the Optimove system that a visitor/customer has visited a page within your website.

Event structure:

{
    "tenant": int,
    "event": "set_page_visit",
    "context": {
        "event_device_type": "Mobile/Web",
        "event_native_mobile": true, // false,
        "event_platform": "<platform Ex. iOS/Android>",
        "event_os": "<operating system Ex. iOS 13.5.0>",
        "customURL": "<URL>",
        "pageTitle": "<pageTitle>",
        "category": "<category>"
    },
    "visitor": "<visitorid>",
    "customer": "<customerid>",
    "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
}

Set Page Visit notes:

For set page visit events, "customURL", and "pageTitle" are mandatory parameters.

Using Pre-Defined Events for a Registration Scenario

A common scenario in which you may want to reach out to your visitors immediately is upon their registration to receive email communications.

In order to accomplish this, Optimove will need to receive the predefined events mentioned above in this sequence, within an array:

[
    {
        "tenant": int,
        "event": "set_user_id_event",
        "context": {
            "event_device_type": "Mobile/Web",
            "event_native_mobile": true, // false,
            "event_platform": "<platform Ex. iOS/Android>",
            "event_os": "<operating system Ex. iOS 13.5.0>",
            "userId": "<customerid>"
        },
        "visitor": "<visitorid>",
        "customer": "<customerid>",
        "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
    },
    {
        "tenant": int,
        "event": "set_email_event",
        "context": {
            "event_device_type": "Mobile/Web",
            "event_native_mobile": true, // false,
            "event_platform": "<platform Ex. iOS/Android>",
            "event_os": "<operating system Ex. iOS 13.5.0>",
            "email": "<email>"
        },
        "visitor": "<visitorid>",
        "customer": "<customerid>",
        "timestamp": "<event timestamp Ex. 2020-05-26T07:40:45.495Z>"
    }
]

Consent Management Event

This event provides the ability to update the subscription status of each customer in realtime. After reporting this event, your customers' subscription status will be updated in the SendGrid suppression list (includes or excludes the relevant email address) and in the OptiMail unsubscribe attribute.

Event structure:

{
    "tenant":int,
    "event": "consent",
    "context": {
        "brand": "brand id",
        "opt_in": false/true,
        "identifier": "email",
        "event_origin": "server",
        "execution_method": "email",
        "channel_id": 15
    },
    "customer": "<customerid>"
}

Important notes:

All parameters in the structure are mandatory
The brand ID and the tenant's Id can be provided by your CSM
Event and parameter names are case sensitive.

Visitor Management for Server-Side Events

When implementing T&T using server-side events, Optimove is not the entity generating visitor IDs.

You may still accumulate data and target visitors with Triggered Campaigns, however, the visitor ID management must be taken care of independently and external to Optimove.

Important notes:

Should you decide to manage the visitor’s identity on your server/backend, in order to ensure events are correlated correctly, visitorID consistency must be maintained when sending different events generated by the same visitor.
Upon visitor conversion, in order to ensure events, that were generated while in a visitor state, are correctly attached to the customer, a "set_user_id_event" must be sent with the correct mapping between the visitor and customer IDs.
Visitor IDs must be less than 200 characters

Server-Side Supported Capabilities

- - All server-side events are tracked and made available for customer-level analysis and target group creation through Optimove’s ‘Web & App Activity’ criteria.
  - All server-side events are made available for campaign-triggering purposes.
  - Triggered campaigns, based on server-side events, can be executed via one of these execution channels:
    - OptiMail
    - OptiMobile Channels (the Optimove Mobile SDK and Web SDK are required to send mobile and web messages respectively).
    - OptiText
    - API

Enabling Optimove’s Server-Side API

Reporting Server-Side Events (API V2)

Overview

Error Codes

Server-side events must be reported using the following structure

Body

Schema

Sample Request

Headers

Schema

Example

Sequential Events

Pre-Defined Events

Set Email Event

Set User ID Event

Set Page Visit

Using Pre-Defined Events for a Registration Scenario

Consent Management Event

Visitor Management for Server-Side Events

Server-Side Supported Capabilities

Related articles