Headless Integration

Integrate Releva in 12 easy steps for Apps and headless e-commerce platforms.

This page will guide you through a full integration of your shop or app with Releva using APIs only. If you have a standard e-commerce shop or platform and have access to your frontend, please refer to our standard integraiton guide instead.

Please note that you should only call Releva’s API on behalf of clients who have given you consent to do so under GDPR.

Step 1: On each page (screen)

Please make the following API call.

• It’s important to set the x-forwarded-for header with the visitor’s IP in order for Releva’s geolocation to work properly.

curl -H 'X-Forwarded-For: <clientIp>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <accessToken>' -XPOST https://releva.ai/api/v0/push -d'{
  context: {
    "profileId": ."..",
    "sessionId": "...",
    "mergeProfileId": "...",
    "profileIdChanged": true/false,
    "sessionId": "...",
    "isFirstSession": true/false,
    "group": "123,
    "cart": {
        "products":  [
          {
            "id": "",
            "price": 0,
            "currency": "",
            "quantity": 0,
            "custom": {
              "string": [
                {"key": "color", "values": ["red"]}
              ],
              "numeric": [
                {"key": "size", "values": [18]}
              ]
            }
          }
       ]
    },
    "wishlist": {
      "products": [
        {"id": "..."}
      ]
    },
    "profile": {
      "firstName": "",
      "lastName": "",
      "email": "",
      "phoneNumber": "...",
      "registeredAt": "YYYY-mm-ddT00:00:00.000Z",
      "location": {"lat": 39.9352959, "lon": 23.5825895}
    },
    "profileChanged": true/false,
    "cartChanged": true/false
  },
  options: {}
}'

Note that you need to convert the phone number to a valid international format (e.g. if your shop operates in the U.S., you need to change 585-766-1234 to +15857661234; if the phone number cannot be converted in this way, do not include it in the request).

Hint: Whenever the user’s cart has changed, please send the same request as above with the updated cart contents. If a user removes the last item from their cart, and their cart is deleted, please send a request with the same body but with an empty products list. Example below:

...
"cart": {
  "products": []
},
...

The context Object

The Context Object has the following structure. All fields are required unless stated otherwise.

The context.cart Object

This object describes the current state of the visitor’s cart. It should be set whenever a visitor’s cart is not empty.

The context.profile Object

This object describes the currently logged-in visitor. It should be set whenever a visitor is logged in.

The context.wishlist Object

This object describes the wishlist.

Step 2: On product pages

Find the call to /api/v0/push you added in Step 1. Then, add the following to the context parameter:

"page": {
  "token": "<yourProductPageToken>",
  "categories": ["men/shoes/sport"]
},
"product": {
  "id": ""
}

The context.page Object

The Context Object describes the page the user is currently viewing. All fields are required unless stated otherwise.

The context.product Object

This object describes the currently viewed product if the visitor is on a product page. In all other cases, it should not be set.

Step 3: On the product listing page (e.g. category page)

Find the call to /api/v0/push you added in Step 1. Then, add the following to the context parameter:

"page": {
  "token": "<yourProductListingPageToken>",
  "ids": [],
  "categories": ["men/shoes/sport"],
  "filter": {
    "operator": "and",
    "nested": [
      {"key": "price", "operator": "gte", "value": "10", "action": "include"},
      {"key": "price", "operator": "lte", "value": "50", "action": "include"},
      {
        "operator": "or", 
        "nested": [
          {"key": "custom.string.size", "operator": "eq", "value": "42", "action": "include"},
          {"key": "custom.string.size", "operator": "eq", "value": "43", "action": "include"},
        ]
      }
    ]
  }
}

The context.page Object

The Context Object describes the page the user is currently viewing. All fields are required unless stated otherwise.

The context.page.filter object

This is an object with the following properties:

The context.page.filter.nested array

This is an array of conditions used for the filter with the following properties:

Step 4: On search and search result pages

Find the call to /api/v0/push you added in Step 1. Make sure that your context.page object contains the ids property that will show the result from a search and a query object that defines the query of the user. Also include the filter object (see the previous step for detailed specification).

"page": {
  "token": "<tokenOfAnyPageWithSearchCapability>",
  "query": "my simple query",
  "ids": ["productId_id1", "productId_2", "productId_3"],
  "filter": {
    "operator": "and",
    "nested": [
      {"key": "price", "operator": "gte", "value": "10", "action": "include"},
      {"key": "price", "operator": "lte", "value": "50", "action": "include"},
      {
        "operator": "or", 
        "nested": [
          {"key": "custom.string.size", "operator": "eq", "value": "42", "action": "include"},
          {"key": "custom.string.size", "operator": "eq", "value": "43", "action": "include"},
        ]
      }
    ]
  }
},
...

Note that if you add the optional query parameter, the system will also add a search event. We highly recommend adding the ids field that must represent the result of the search query. The locale must represent both the page and query locale. In the rare event when they differ you shall describe search locale as a custom property.

Step 5: On checkout success pages

Find the call to /api/v0/push you added in Step 1.Then, change your cart[].products to contain not the list of products in the user’s cart, but the list of products that were part of the newly placed order.
Include the profile object with email and phoneNumber, if you have them (at least one is required, send both if you have both). Please ensure that the profile object is passed even if the order was placed via guest checkout and not by a registered user.

Note that you need to convert the phone number to a valid international format (e.g. if your shop operates in the U.S., you need to change 585-766-1234 to +15857661234; if the phone number cannot be converted in this way, do not include it in the request).

...
     "cart": {
        "products":  [
          {
            "id": "id_of_ordered_product",
            "price": 1,
            "currency": "USD",
            "quantity": 2,
            "custom": {
              "string": [
                {"key": "color", "values": ["red"]}
              ],
              "numeric": [
                {"key": "size", "values": [18]}
              ]
            }
          }
       ]
    },
    "profile": {
      "firstName": "",
      "lastName": "",
      "email": "",
      "phoneNumber": "+15857661234",
      "registeredAt": "YYYY-mm-ddT00:00:00.000Z",
    }
...

Step 6: Render Personalization Results

A successful request to the /api/v0/push endpoint will return a response with the following structure (below):

• Recommenders – this array contains a list of recommenders enabled on this page (the page is identified by the context.page.token you included in the request). Each reocmmender will have a name, a unique token, and a list of products under responses. Each response represends a product with information that Releva has for this product. In addition, there is a mergeContext field which we use to attribute user actions to Releva. This information should be sufficient to visualize the products in your website or app. IMPORTANT: If the visitor clicks on a recommended product, you need to merge the mergeContext values into the context object the next time you call the Push API.
• Banners – this array contains a list of banners enabled on this page (the page is identified by the context.page.token you included in the request). Each banner will have a name, a unique token, and an HTML body. . In addition, there is a mergeContext field which we use to attribute user actions to Releva. This information should be sufficient to visualize the banner in your website or app. IMPORTANT: If the visitor clicks on a recommended product, you need to merge the mergeContext values into the context object the next time you call the Push API.
• Push – this contains the public key (vapidPublicKey) that Releva will use to sign push notifications.

{
  "recommenders": [
    {
      "token": "916c829e-c1eb-4f49-81ec-106ab8471f3b",
      "name": "Trending from This Category",
      "meta": {
        "algorithm": "hot"
      },
      "tags": ["t1", "t2"],
      "cssSelector": "body",
      "displayStrategy": "befeoreend",
      "template": {"id": 123, "body": "..."},
      "response": [
        {
          "available": true,
          "categories": [
            "cat1"
          ],
          "createdAt": "2019-08-18T05:48:42.419Z",
          "currency": "BGN",
          "custom": {
            "string": [
              {
                "values": [
                  "bar"
                ],
                "key": "f"
              }
            ]
          },
          "data": {
            "foo": "bar"
          },
          "description": "Some Description",
          "discount": 0,
          "discountPercent": 0,
          "discountPrice": 0,
          "id": "3847012384816",
          "imageUrl": "https://cdn.shopify.com/s/files/1/0263/8328/6320/products/yes-me-me-me-me_286x381.jpg?v=1565038619",
          "listPrice": 2500,
          "locale": "bg",
          "mergeContext": {
            "rid": "...",
            "rpid": "..."
          }
          "name": "Test Product",
          "price": 2500,
          "publishedAt": "2019-12-25T12:41:30.457Z",
          "updatedAt": "2019-12-25T12:41:30.457Z",
          "url": "https://releva-dev.myshopify.com/products/test-product?rlv_rid=916c829e-c1eb-4f49-81ec-106ab8471f3b",
        }
      ]
    },
    ...
  ],
  "banners": [
    {
      "token": "9f4625ea-4ef1-4503-b55c-f11c13e25a60",
      "name": "Test Banner",
      "html": "<html>\n  Hello World!\n</html>",
      "tags": ["t1", "t2"],
      "mergeContext": {
        "bid": "..."
      },
      "displayType": "popup",
      "delaySeconds": 123,
      "scrollPercentage": 23,
      "cssSelector": "body",
      "trigger": null
    },
    ...
  ],
  "push": {
    "vapidPublicKey": "..."
  }
}

Step 7: Register users for push notifications

If you do not plan on using Releva to send push notifications, you may skip this step.

Please make the following API call. In order to generate the keys required for Releva to send the push notification for each user, you would need to add Releva’s public key, which you can obtain from the push.vapidPublicKey in Releva’s response (see previous step).

curl -H 'Content-Type: application/json' -XPOST https://releva.ai/api/v0/pushSubscriptions/<accessToken> -d'{
  "context": {
    "profile": {
      "email": "...",
      "phoneNumber": "..."
    }
  },
  "subscription": {
      "endpoint": "...",
      "expirationTime": null,
      "keys": {
        "auth": "...",
        "p256dh": "..."
      }
   }
}'

The context Object

This object describes the currently logged-in visitor. It should be set whenever a visitor is logged in.

The subscription Object

This object describes the currently logged-in visitor. It should be set whenever a visitor is logged in.

Step 8: Call the poduct update API call when changes in your catalogue occur

This is necessary for ensuring that changes in your catalogue are reflected in Releva in a timely manner. See Product Update for implementation details.

Step 9: Call the cart paid API when a customer places an order

See Cart Paid API for implementation details.

Step 10: Implement the periodical product sync API

This ensures that Releva will learn about changes in your catalogue even if your Product Update call does not work. It is highly recommended to implement this fallback mechanism. See Periodical Product Sync for implementation details.

Step 11: Send subscribes and unsubscribes to Releva

If you do not plan on using Releva to send emails or text messages, you may skip this step.

1. When a user wishes to unsubscribe from receiving email or other marketing communication through Releva, you need to call the Unsubscribe API to notify Releva.
2. When a user wishes to subscribe to receiving email or other marketing communication through Releva, you need to call the Subscribe API to notify Releva.

Step 12: Send newly registered users to Releva.

When a new user registers on your shop, you need to call the Profile Register API to notify Releva.

All Set!

Congratulations! This concludes the integration of your shop. Releva offers some advanced features that will help you achieve even better results. Feel free to explore the API Specification for information about how to send custom product and profile data, which can later be used in personalization. Also, feel free to look into the Data Deletion API and the Retrieve Tracked Data API which is designed to help you fulfill GDPR-related requests automatically.