Motionlab

This guide will help you generate and distribute personalized video campaigns to targeted audiences by integrating Bloomreach Engagement with Motionlab Adina.

Why use this integration?

Bloomreach Engagement CDXP can be integrated with many services to improve personalized communication. Together with Motionlab Adina, you can generate personalized video campaigns and automatically distribute them to specifically targeted audiences with the help of Bloomreach Engagement.

Bloomreach Engagement and Motionlab Platform can exchange data via webhooks. First, Bloomreach Engagement pushes the information on what data will be used to generate the personalized videos to Motionlab.

Once the videos are rendered, Motionlab will push back the URLs to the personalized videos for each customer profile. These can be embedded, for example, in an email or other forms of communication afterwards.

👍

Case study with MALL.CZ

MALL.CZ recorded an 11x increase in email click-through rate and a 701% increase in product purchases with personalized videos using Engagement and Motionlab. Read about their success story.

Setup process

Basic implementation

The goal of the implementation is to set up data transmission between the Motionlab and Bloomreach Engagement API services.

• On the Bloomreach Engagement side, we recommend creating a dedicated private access API Group for Motionlab. This will let Motionlab use its own dedicated API Key ID/API Secret key pair for the API communication.

• On the Motionlab side, select the API mode and Exponea preset when creating a new campaign in Adina.

Follow the instructions below to complete the integration setup.

1. Check your prerequisites first. Those are:

   • Having Motionlab account
   • Using registered as a client ID

2. Create your private API group in Bloomreach Engagement specifically for Motionlab. How to set it up, check out our detailed guide for creating API groups.

3. Create a new campaign in Motionlab. Select “API mode” and “Exponea preset”.

4. Go to “Launch” in Motionlab and fill out your information such as base URL, project token, access keys. Now Motionlab is set.
5. In Motionlab, find your ‘api key‘ and ‘campaign key‘.
6. Create a scenario with a webhook node in Bloomreach Engagement.
7. Add the payload example into a webhook set-up. Use the API key from step 5 which you found in Motionlab.
8. Motionlab callback ‘(more details are in Integrating Motionlab section)’.

Integrating Motionlab

Important Campaign parameters and where to get them:

• API key can be found in the Launch step in the Campaign detail. In this guide, we will use a variable apiKey.
• Campaign key can be found in the Campaign settings (accessible under the Campaign name). The Campaign key is the same for all videos in the Campaign. In this guide, we will use a variable campaignKey.

We need these parameters for Bloomreach Engagement integration (can be set in the Launch step):

• API Base URL of Exponea instance (for example: https://api.exponea.com)
• Project token
• Public and Secret key
• Set Customer Id key by Exponea settings

For full API documentation beyond these texts, see Motionlab documentation.

Webhook Payload (to Motionlab endpoint)

Method: POST
URL: https://api.motionlab.io/v2/render?apiKey={apiKey}
Content-Type: application/json; Encoding: UTF-8

{
    "videoData": {
        "customParamText": "Hello World!",
        "customParamNumber": "123",
        "customParamBoolean": "true",
        "customParamImage": "https://www.motionlab.io/photo.jpg",
        "customParamPlace": "Prague",
        "customParamEnum": "prg",
        "customParamPage": "https://www.motionlab.io",
        "...": "..."
    },
    "integrationData": {
        "eventType": "exponeaEvent",
        "customerIds": {
            "registered": "customer1"
        }
    }
}

The payload is created from the campaign parameters and Bloomreach Engagement parameters eventType (an event called in Bloomreach Engagement when the video is generated) and customerIds (the identification parameters) which is Registered (HardIds) identification in Bloomreach Engagement.

It is necessary to send requests and process responses and callbacks in UTF-8 encoding; otherwise, the requests could be ignored, or the flow could work incorrectly.

Set up a Retry policy in Bloomreach Engagement to the 0 retry attempts, so that the video won’t be generated as a charged duplicate in case of a longer API response.

Also, set up a Throughput policy in the Webhook settings with a concurrency limit lower or equal to 10 requests per second (for wider network bandwidth, please contact Motionlab directly). In case of launching large campaigns, contact Motionlab for the possibility of increasing the concurrency limit.

Motionlab Callback (from Motionlab endpoint)

The callback is made after the video is successfully generated.
Method: POST
Content-Type: application/json; Encoding: UTF-8

{
  "customer_ids": {"registered": "customer1"},
  "event_type": "exponeaEvent",
  "properties": {
    "MASTERCOMP": "https://api.motionlab.io/videos/{campaignKey}/{id}",
    "THUMBNAIL_0": "https://api.motionlab.io/images/{campaignKey}/{id}?type=thumbnail_0",
    "THUMBNAIL_1": "https://api.motionlab.io/images/{campaignKey}/{id}?type=thumbnail_1" 
  }
}

Legend:

• campaignKey is the same for all videos and thumbnails for the Campaign
• id is unique for the set of the video and thumbnails in one API request
• In case data in the API request are not valid or not accessible (e.g. images), the status code 400 (Bad Request) is returned
• In case the API endpoint is not launched, the status code 401 (Unauthorized) is returned

There is also a possibility that the video could not be created because of the influence of 3rd party services like Content delivery providers (external images failed to be downloaded, for example). In these cases, Motionlab is sending back a callback informing about the reason for failure. This callback can also be processed in Bloomreach Engagement.

You can find out more about callbacks and how to generate a video in the Motionlab documentation under Generate personalized video section.

Test mode

For cases where testing the functionality and availability of all services is needed, the ‘isTest’ parameter can be added to generate a video endpoint payload.

This change will trigger actions where no video is generated, no credit is subtracted, but a 'universal' video is returned. All callbacks are sent like in the 'standard' model.

{
    "videoData": {
        "customParamText": "Hello World!",
        "...": "..."
    },
    "integrationData": {
        "eventType": "exponeaEvent",
        "customerIds": {
            "registered": "customer1"
        }
    },
    “isTest: “true”
}

You can find out more about test mode and how to generate a video in the Motionlab documentation under Generate personalized video section.

Bloomreach Engagement showcase flow

When sending the data from Bloomreach Engagement to Motionlab Adina, you can use a manually triggered scenario with Webhook.

First, you need to create a scenario where it is triggered ‘On event’ or ‘On date’ to have a manually triggered scenario. Then you can add a ‘Wait’ node. It needs to contain dynamic data such as an expression, segmentation or aggregates through the Condition node. After this node, you need to add a webhook node with a specific setting for Motionlab, as mentioned above. One example could be a scenario triggered on a ‘Purchase event’ with a wait function of a few days. Then, customers must have more than 2 purchases to get a video campaign through our webhook node.

By defining the event name in the Webhook Payload, this event will be triggered when the video is generated.

Events that fire a scenario in Bloomreach Engagement after Motionlab callout could be any campaigns with designed video such as opened email or SMS.