Server-Side Integrations

Traditionally, you use the Monetate tag on your site to test and personalize changes for your customers. For performance and flexibility reasons, Monetate allows you to do this with a server-side integration through the Engine API, a direct entry point into the platform's decision engine. The platform looks up customer data, including historical behavior, across channels in real time, and the Engine API returns decisions and actions when you send a request from the API that includes events and all experiences configured for a particular channel.

This concept, as well as its implementation, is not Web-specific. You can use it in any channel, including mobile apps.

Contact the Enterprise Integration team if you want to use a server-side integration for your account.

Closing the Loop

The Engine API serves two main functions:

  • Event stream: To make the best decisions, Monetate needs to understand site visitor behavior because it adds valuable targeting information and context for the platform's machine-learning algorithms. Additionally, the Engine needs to recognize conversion events to optimize for them.
  • Decisions: The Engine API returns actions based on the experiences configured within the platform and the action alternatives within each.

Illustration of the two main functions of the Engine API

You can send the event stream with the same Engine API endpoint used for decisions. Events can be sent in the same call or separately.

Mobile Apps

Mobile apps are often already integrated with advanced analytics tools such as mParticle. In this case, Monetate can connect to this platform and subscribe to the event stream from your app to receive all events triggered by your customers using your application. There's no need to add events to the Engine API calls. As long as you can send the same customer or device ID to both systems, Monetate can join the data together.

Requesting In-the-Moment Decisions

Monetate's API for server-side integrations is based on a single REST endpoint that allows you to do three things with a single call:

  • Send information about the current visitor (such as a user ID), the request (such as the client IP address or requested URL), and additional context (such as the product IDs on the page or the page type)
  • Retrieve all actions that are supposed to fire in the current context; these actions can be part of any experience in Monetate and can be a mix of personalized content and tests to activate.
  • Send any events/success metrics to Monetate to measure success

Bundling all these capabilities into a single endpoint allows you to receive all your data with a single call, thereby reducing latency when you transmit to Monetate.

The code below provides an example of a sample request.

  deviceId: '2.1905360897.1482428295027',
  monetateId: [],
  customerId: ['123456789'],
  events: [{
      eventType: 'monetate:context:ProductView',
      pid: ’ABC123’
      eventType: 'monetate:decision:DecisionRequest',
      account: 'a-12345678',
      requestId: '12345'

Events allow you to send arbitrary data with any request to Monetate. This table provides a brief description of some common event types.

Event TypeDescription
monetate:context:IpAddressIPAddress of the customer who originates the request to enable IP and geolocation targets
monetate:decision:DecisionRequestUsed to make a request for decision-making, and Monetate attaches all actions that apply to the reply; if you omit this, Monetate only processes the events and success metrics
monetate:context:UserAgentUser-agent header from the customer who originates the request
monetate:context:PurchaseUsed to communicate a purchase; must include all line items that are part of the purchase
monetate:context:ProductViewUsed to communicate product views and to send a list of viewed product IDs to Monetate
monetate:context:MetadataUsed to communicate additional metadata (key/value pairs) that Monetate may need for actioning

API documentation with all event types and response specifications is available within the Monetate platform. Click the settings cog, select API Documentation, and then click API Documentation under the Monetate Engine API heading in the left-hand category listing.

Taking Action

The code sample below is an example reply to the request described above.

  "responses": [{
      "requestId": "12345",
      "actions": [{
          "data": "{
          'slot': 'startscreenhero',
          'content': '/img/specialvip_sale.jpg'
        "actionType": "monetate:action:OpenAction",

In this example the Engine needs to consider only a single action for the current state with the configuration parameters as shown. Your customer's app doesn't need to take action on this and change the source of the image in the slot startscreen_hero accordingly.