Personalize API

Overview

Personalize APIs are a collection of endpoints that may be accessed from your website's code. These APIs offer personalization capabilities and must be invoked from your codebase for MoEngage to provide relevant data. After receiving the data, you can use the same within your website's code to personalize the content for your users.

Benefits of server-side testing

  1. Speed & User Experience: If enhancing load times is a priority, server-side tests are most beneficial. They have quicker loading times than client-side experiments because they handle the variation before the page is sent from the server, eliminating any delay in page rendering that could occur with client-side testing. It avoids the flickering effect that sometimes happens in client-side testing when changes are made during or after the page load.

  2. Complex Experiments: If you want to conduct a complex experiment that involves testing different algorithms, back-end processes, or core business logic, server-side testing would be the right choice. This could include things like testing a new recommendation algorithm for products or articles or trying out new pricing logic or a new checkout flow.

  3. SEO-Friendly: As the content is rendered at the server level and sent to the client’s browser, server-side testing is more SEO-friendly than client-side testing. The changes made through server-side testing will be properly indexed by search engines.

  4. Security: Server-side testing is more secure as the logic resides on your server, not on the client's browser. It's ideal for testing sensitive areas, like payment processing or account login that require additional security measures.

  5. Consistency Across Devices: If you wish to ensure that your experiment doesn't get affected by the user's device or browser limitations, server-side testing is the best bet. This is especially useful if you're aiming for a uniform user experience across different devices and browsers.

When to use Server-side experimentation

While Server-side testing offers a powerful methodology to run intricate experiments at a deep level, there are several factors to consider before deciding if it’s the right approach for your requirements:

  1. Technical Expertise: Server-side testing generally requires a higher level of technical knowledge than client-side testing, as modifications need to be made to the server-side code. Hence, you would need access to proficient developer resources and support.

  2. Cost: Server-side testing generally demands more development time and resources compared to client-side alternatives.

  3. Speed of experimentation: If you need to conduct rapid iteration tests and observe quick results, client-side testing could be more beneficial due to its higher implementation speed.

API Endpoints

Fetch experience

Use the Fetch endpoint to receive data on active personalization experiences. You can fetch data for one or more server-side experiences by using the experience-key field. MoEngage will evaluate targeting rules and in-session attributes automatically and return the correct variation for the user. Typically, you would make this call as part of your larger page and content rendering pipeline.

API Endpoint
POST https://sdk-0X.moengage.com/v1/experiences/fetch

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Reporting Impressions

With Server side personalization, the experience is personalized at the server. The MoEngage SDK does not record an impression on its own.

 

To report an impression for your campaign, use the below MoEngage SDK function

JavaScript
window.addEventListener("MOE_LIFECYCLE",function(e){
if(e.detail.name === "SDK_INITIALIZED"){
window.Moengage.web_p.trackImpression(experienceContext);}
})

experienceContext is a JSON object that is returned in the response of the Server-side experience Fetch call. More details here.

Reporting Clicks

Users engage with your webpage by clicking on the different links or CTAs present on it. Apart from measuring impressions, reporting clicks is important to gauge the success of your campaign and improve performance.

To report a click for your campaign, use the below MoEngage SDK function

JavaScript
window.Moengage.web_p.trackClick(experienceContext, extraAttributes);

experienceContext is a JSON object that is returned in the Response of the Server-side experience Fetch call. More details here.

experienceAttributes is a JSON object in which you can pass additional information about the link or the CTA which the user has interacted with.

JSON
{
  "widget_id": "<alphanumeric value>"
}

 

Key Description Sample Values
widget_id This key is used to identify either a link or CTA uniquely. If the visitor clicks on the same link or CTA across multiple visits, ensure to send the same value  for the link/CTA in each session AlphaNumeric value. 

 

Passing deviceID back to the Server

A first-time anonymous visitor to your website is eligible for experiences that are configured for All Users and/or based on In-session Attributes. Such a visitor who visits a site that contains the MoEngage Web SDK is assigned a specific ID called as deviceID. This deviceID is stored in cookies, session storage, and local storage of the browser. 

The deviceID is not a unique identifier for the user. The same user could be assigned another deviceID in any of the following cases:

  • The user uses a different browser or a different device. 
  • The user deletes the cookies, cache, and local storage of the browser.
  • The user enters the site using incognito mode.
  • The user returns to the site after the expiration of the cookie storing the deviceID.

When a first-time anonymous visitor is shown a personalized experience, it is recommended to pass the deviceID generated by MoEngage back to the server. For future sessions of the same user, this deviceID can be used to fetch personalized experiences from the server. Use the below function to fetch the MoEngage deviceID.

Javascript
Moengage.device.getUuid()

deviceID needs to be passed as the value for the key visitor_id as part of the request to fetch Server side experience. deviceID needs to be sent only if the unique identifier for the user is not available

If the user logs into the website using a unique identifier (email, phone number etc.) then a unique identifier is assigned to the user and this serves as 1:1 mapping for the user. This identifier can be used for future sessions of the user. 

The unique identifier needs to be passed as the value for the key user_id as part of the request to fetch Server side experience.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard.

  1. Navigate to Settings -> Account -> APIs.

  2. Click the Copy icon in the Personalize tile in the API Keys section to copy the API Key.

  3. Use the App ID as the username and the Personalize API Key as the password to generate the authentication header.

Regenerate API SECRET

The API SECRET can be regenerated on the MoEngage Dashboard in the Personalize API Settings section discussed above.

Please DO NOT regenerate the key unless there is a security breach. Once you generate a different API SECRET KEY and save it, API calls using the older SECRET KEY won't work.

Request Headers

Key

Sample Values

Description

MOE-APPKEY

{"MOE-APPKEY": "APP ID"}

This is the APP ID of your MoEngage account and needs to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. For more information, refer to Authentication.

Authorization

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

Content-Type

application/JSON

Set the Content-Type header to application/JSON for using the Personalize API.

Request Body

Key

Mandatory

Value

Description

user_id

No

String

This field is provided by your brand and should be pasted in the request. This field is the Client ID and identifies the user to whom the personalized content is to be shown. This is essential for event mapping back to the user. 

If an Invalid User ID or non-existent User ID is shared and the API request has valid recipient details, a new user profile would be created with valid recipient details.

If user_id is not present in the request, the request will still be processed by considering the value of the visitor_id field. If the value for the visitor_id field is not present in the request, the events will not be logged to any user in MoEngage.

visitor_id

No

String

This field is provided by the MoEngage SDK and should be pasted in the request if there is no unique id associated with the user. This is generally used for users who have visited your website in the past but have not logged in or created an account on your website.

The value for a visitor id can be fetched, as explained here

experience_key

Yes

String

This field is used to uniquely identify each server-side experience created using MoEngage Personalize. You can pass multiple values in a single request and receive the personalized content defined for each experience in the response.

platform

No

String

This field identifies the platform used by the visitor to engage with your brand. Accepted values - web

DAY_OF_THE_WEEK

No

String

This field must contain the day of the week for evaluating IN-session attribute-based experiences. Accepted values - Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

TIME_OF_THE_DAY

No

String

This field must contain the time of the day for evaluating IN-session attribute-based experiences. Accepted values - 00, 01, 02, 03, 04, 05, 06, 07,….., 23
00 stands for time period between 12 AM - 1 AM; 01 stands for time period between 1 AM - 2 AM and so on.
Example: For a time interval between 7 PM - 11 PM, the input for this field should be “19,20,21,22”

USER_IP_ADDRESS

No

String

This field must contain the user’s IP address for evaluating geo-location-based experiences.

USER_AGENT

No

String

This field must contain the USER-AGENT HTTP header. This is essential to deliver personalized content based on in-session attributes like Device Type.

Sample Requests

cURL Node.js Go PHP Python Ruby Java
curl --location 'https://sdk-01.moengage.com/v1/experiences/fetch'  \
--header 'Accept: */*' \
--header 'Authorization: Basic RE1RNjFOVk0xQjJKRUs4VVNCUzFIMUNPOg==' \
--header 'Content-Type: application/json' \
--data '{
  "app_id": "KU1MKAGZROCE4NQ1VO0VGJLO",
  "user_id": "Unique identifier for the user like email or phone number",
  "visitor_id": "ID generated by MoEngage for an anonymous user",
  "Custom_attribute":"Attribute Value. Example: utm_medium: email",
  "experience_key": ["new-serverside-experience"],
  "DAY_OF_THE_WEEK": "Tuesday",
  "TIME_OF_THE_DAY": "01",
  "USER_IP_ADDRESS": "136.226.253.9",
  "USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
}'

Response Body

Key

Description

payload

This field contains a list of all the key-value pairs defined as part of the experience

value

This field contains the value of the keys defined in the payload

data_type

This field contains the value of the keys defined in the payload

experience_context

This field returns a JSON object that is to be used for reporting pageviews/impressions and/or tracking clicks within the personalized experience. Refer here for more details 

 

Sample response

JSON
{
  "experiences": {     
      "new-serverside-experience": { 
        "payload": {
            "Title": {
              "value": "Presenting MoEngage Server side personalization! ",
              "data_type": "string"
            },
            "Image": {
              "value": "https://cdn.pixabay.com/photo/2021/02/24/20/53/abstract-6047465_960_720.jpg",
              "data_type": "string"
            },
        },
        "experience_context": {
            "cid": "65eae5738ea5032b0ef60138_F_T_WP_AB_2_P_0_AU_42D",
            "experience": "Server Side Experience",
            "moe_locale_id": "<id>",
            "moe_variation_id": "<id>",
            "audience_name": "<audience name>",
            "audience_id": "<id>",
            "type": "Web Personalization"
        }
      }
  }
}

Response Codes

Status Code

Request State

Description

200

Success

This response is returned when the request is submitted to MoEngage.

400

Bad Request

This response is returned incase the payload is empty or invalid.

401

Authorization Failed

This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.

500

Internal Server error

This response is returned when the system runs into an unexpected error. You can try for a maximum of 3 times with exponential backoff.

 

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?