Calling the Engine API
User Identity Persistence in Requests

Monetate identifies anonymous visitors and tracks behavior via a monetateId. This ID is generated on the first request to the platform if it's not already present and identifies a unique device or browser. In a traditional Monetate JavaScript API﻿ implementation, monetateId is set as a first-party cookie, mt.v. It persists for future site visits.
For Engine API implementations, however, Monetate generates a monetateId if no identifier is passed in the request.
Because Monetate has no way to set the mt.v cookie in an Engine API implementation, the requesting application is responsible for keeping track of the monetateId by setting the cookie or otherwise storing or maintaining the persistence of the value by other means unique to your application.
If a device ID is available that can uniquely identify the customer's device across requests, then you can alternatively include deviceId in all Engine API requests. This value then acts as a unique identifier and allows Monetate to track visitor behavior throughout the current session and across future sessions.
To summarize user identity persistence options for Engine API clients:
monetateId — Can be used for an application and must stored in a variable on your end.
deviceId — Can be used as an alternative to monetateId to identify the customer's device across requests that doesn't need to be stored. This value acts as a unique identifier and allows Monetate to track customer behavior throughout the current session as well as across future sessions.
Whether you use monetateId or deviceId to identify the customer, you must include it in all requests for both current and future sessions.
Hybrid Implementations
For hybrid implementations﻿, ensure that you do the following:
If a monetateId exists in the mt.v cookie, then you must pass it in all Engine API requests.
If no existing monetateId is present in an mt.v cookie, then you must ensure that the monetateId generated by the initial Engine API request is set as a first-party cookie named mt.v, which is case-sensitive.
These user identity measures allow Monetate to reconcile information collected by both the Engine API and the Monetate tag﻿ into a single unified session.
You must take these measures to ensure the seamless functioning and optimal performance of your hybrid implementation. Failure to do so can result in a variety of issues, including disconnected user experiences and inaccurate data tracking.
Contact your dedicated Customer Success Manager (CSM) if you need assistance with these steps.
monetateId Example Requests
New Visitor Request
This example of a New Visitor request has no monetateId. In the response Monetate includes it.
New Visitor Request Without monetateId
New Visitor Response
{
  "channel": "a-12345678/d/example.test",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "127.0.0.1"
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.test/path"
    }
  ]
}
{
  "channel": "a-12345678/d/example.test",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "127.0.0.1"
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.test/path"
    }
  ]
}
﻿
Returning Visitor Request
A monetateId is included in this example Returning Visitor request, which is mirrored in the response.
Returning Visitor Request Without monetateId
Returning Visitor Response
{
  "channel": "a-12345678/d/example.test",
  "monetateId": "5.977810341.1521134874631",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "127.0.0.1"
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.test/path"
    }
  ]
}
{
  "channel": "a-12345678/d/example.test",
  "monetateId": "5.977810341.1521134874631",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "127.0.0.1"
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.test/path"
    }
  ]
}
﻿
deviceId Sample Requests
New Visitor Request
In this example New Visitor request, deviceId is passed instead of monetateId. In this scenario, it's a New Visitor request because Monetate hasn't received this deviceId before. In the response, Monetate doesn't include the deviceId but instead returns monetateId, which can be ignored in this instance.
New Visitor Request with deviceId
New Visitor Response with monetateId
{
  "meta": 
  {
    "code": 200,
    "monetateId": "5.977810341.1521134874631"
  },
  "data": 
  {
    "responses": 
    [      
      {
        "requestId": "11111",
        "actions": 
        [          
          {
            "data": 
            {
              "example": "json"
            },
            "actionType": "monetate:action:OmniJson"
          }
        ]
      }
    ]
  }
}
{
  "meta": 
  {
    "code": 200,
    "monetateId": "5.977810341.1521134874631"
  },
  "data": 
  {
    "responses": 
    [      
      {
        "requestId": "11111",
        "actions": 
        [          
          {
            "data": 
            {
              "example": "json"
            },
            "actionType": "monetate:action:OmniJson"
          }
        ]
      }
    ]
  }
}
﻿
Returning Visitor Request
When the same deviceId is sent again, Monetate recognizes it and classifies it as a Returning Visitor. As in the response in the New Visitor request that contained a deviceId value, Monetate doesn't include the deviceId but instead returns monetateId.
Returning Visitor Request with deviceId
Returning Visitor Response with monetateId
{
  "meta": 
  {
    "code": 200,
    "monetateId": "5.977810341.1521134874631"
  },
  "data": 
  {
    "responses": 
    [      
      {
        "requestId": "11111",
        "actions": 
        [          
          {
            "data": 
            {
              "example": "json"
            },
            "actionType": "monetate:action:OmniJson"
          }
        ]
      }
    ]
  }
}
{
  "meta": 
  {
    "code": 200,
    "monetateId": "5.977810341.1521134874631"
  },
  "data": 
  {
    "responses": 
    [      
      {
        "requestId": "11111",
        "actions": 
        [          
          {
            "data": 
            {
              "example": "json"
            },
            "actionType": "monetate:action:OmniJson"
          }
        ]
      }
    ]
  }
}
﻿
Custom Variables for New or Returning Visitors
You can pass deviceId and a custom variable﻿ in a request to let Monetate know that this customer is either a new or returning visitor.
Request with deviceId and Custom Variable
{
  "channel": "a-12345678/d/example.test",
  "deviceId": "39hu7lgj05454nj5t4",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "127.0.0.1"
    },    
    {
      "eventType": "monetate:context:CustomVariables",
      "customVariables": 
      [        
        {
          "variable": "Returning_Visitor",
          "value": "True"
        }
      ]
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.test/path"
    }
  ]
}
{
  "channel": "a-12345678/d/example.test",
  "deviceId": "39hu7lgj05454nj5t4",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "127.0.0.1"
    },    
    {
      "eventType": "monetate:context:CustomVariables",
      "customVariables": 
      [        
        {
          "variable": "Returning_Visitor",
          "value": "True"
        }
      ]
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.test/path"
    }
  ]
}
﻿
When you first send deviceId, the Engine API classifies the customer as new. When you use custom variables, you send the custom variable in addition to deviceId to ensure that new visitors are targeted.
Targeting New and Returning Visitors with deviceId and Custom Variables
Use the Custom variable visitors option in the Landing target type to target new and returning visitors when configuring the WHO settings of an experience.
﻿
You can also use the New visitors and Returning visitors options in the Landing target type instead of custom variables.
﻿
Identifying Known Customers Included in a Customer Dataset
You can provide a customerId for logged-in customers of your application. This ID identifies someone in, for example, a loyalty program. It's associated with the identified device and allows you to use your own data that you've uploaded to Monetate in a customer dataset for targeting and context.
For Customer Datasets
This content is only for clients with Product Data and Customer Data options in the DATASETS menu in the top navigation bar of the Monetate platform. If no menu options appear when you click DATASETS, then this content doesn't apply to your account. Instead, see For Customer Attributes Datasets﻿.
You must send monetateId or deviceId with each request.
You cannot use customerId in lieu of monetateId or deviceId.
Request with monetateId and customerId
{
  "channel": "a-1d121c07/p/monetate-api.myshopify.com",
  "monetateId": "5.1824559023.1570975471014",
  "customerId": "123abc",
  "events": [
    {
...
{
  "channel": "a-1d121c07/p/monetate-api.myshopify.com",
  "monetateId": "5.1824559023.1570975471014",
  "customerId": "123abc",
  "events": [
    {
...
﻿
For Customer Attributes Datasets
This content is only for clients with the one-click DATASETS option in the top navigation bar of the Monetate platform. If you click DATASETS and see Product Data and Customer Data listed as menu options, then this content doesn't apply to your account. Instead, see For Customer Datasets﻿.
If you have a Customer View enabled and have a different type of customer identifier, then continue to send customerId for the Customer View and send the Customer Attribute dataset's Identifier Name, which you can find on the Customer Attributes view of the Datasets list page, via a custom variable. You don't need to add the custom variable value for the Identifier Name to an experience.
Request with customerId and Identifier Name in Custom Variable
{
  "channel": "a-1d121c07/p/monetate-api.myshopify.com",
  "customerId": "123abc",
  "events": [
    {
      "eventType": "monetate:context:CustomVariables",
      "customVariables": [
        {
          "variable": "LoyaltyId",
          "value": "1234"
        }
      ]
    }
  ]
}
{
  "channel": "a-1d121c07/p/monetate-api.myshopify.com",
  "customerId": "123abc",
  "events": [
    {
      "eventType": "monetate:context:CustomVariables",
      "customVariables": [
        {
          "variable": "LoyaltyId",
          "value": "1234"
        }
      ]
    }
  ]
}
﻿
Using Customer View with Engine API
It's possible to have a single view of a customer across mobile, desktop, and apps as long as the customerId is the same. Doing so stitches together the behavioral data for the customer for the corresponding behavioral targets supported by a Customer View.
This setup works in Web experiences by matching on the customerId, which then guarantees that Monetate serves the same experience for customer A.
To have this same matching to happen in your Omnichannel experiences, then you must contact the Services team to set up an ID Collector. If your account already has an ID Collector set up for Web experiences, then provide the name so that it can be copied to your app accounts.
Client-side developers must take the following steps:
﻿Create an Omnichannel experience with the Omni JSON action matching the desktop experience to ensure that the customer sees the same visual change.
Pass a customerId in the request along with all relevant or identical target information as context.
The Engine API responds to the request with the eligible experiences.