Moloco Commerce Media Destination

Destination Info
Partner Owned
  • This integration is partner owned. Please reach out to the partner's support for any issues.

Moloco Commerce Media (MCM) is a technology solution that empowers marketplaces and online retailers to build and scale a retail media business (for example, sponsored ads). Moloco’s solution helps platforms leverage and activate their first-party data to deliver highly relevant and performant ads, automate ad decision-making, and scale their ads business.

The Moloco Commerce Media destination can send user events collected using the Segment SDK to Moloco’s platform for a simplified performance ads integration.

This allows you to run performance advertising without having to build your own backend system to ingest and send user events data in realtime to Moloco.

Getting started

Prerequisites

Before you configure the Moloco Commerce Media destination, add a source to Segment and use the Source Debugger to verify Segment is receiving events.

Before you configure the Moloco Commerce Media destination, reach out to your Moloco representative about the following account information:

  • Moloco Platform ID
  • Moloco Event Service API key

After you obtain that account information, you can move on to the Segment app.

Set up your Moloco destination

  1. From the Segment web console, click Catalog.
  2. On the Catalog page, search for “Moloco”, select it, and click Add destination.
  3. Choose which of your sources to connect the destination to.
  4. In the Moloco MCM destination settings page, fill the Platform ID and API key fields with your Moloco Platform ID and Event Service API key.
  5. Select “APP” if your source endpoint is a mobile app, and “SITE” if it is a website.

Identify

Moloco strongly recommends that you identify your logged-in users using Segment’s Identify method and that you hash the user ID before sending it to Moloco.

Please find an example Identify call below:

analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', {
  email: 'john.doe@example.com'
});

Once a user is identified, each call to Segment’s Track method automatically records the user ID. Users that are not logged in can be tracked using an anonymousID. Moloco Commerce Media does not use anonymousIDs for users that are not logged in. Segment recommends formatting your anonymousID in UUID format.

If you hash the user ID before sending it to Moloco, ensure you reuse the same hashed ID when calling other Moloco APIs.

Track

If you’re not familiar with the Segment Spec, take a look to understand what the Track method does. The mappings in the Moloco Commerce Media destination are built based on the Segment Ecommerce Spec.

Please find below an example call to track a product detail page (PDP) view event:

analytics.track("Product Viewed", {
  product_id: "1193",
  name: "Newage Uplift Eye Care Cream",
  price: 19.99
  currency: "USD"
  quantity: 1,
  image_url: "https://www.example.com/image.png"
});

Page

If you’re not familiar with the Segment Spec, take a look to understand what the Page method does.

Please find below an example call to page:

analytics.page();

If you use Segment’s Web SDK, this call automatically collects the page information. Here’s an example of page information automatically collected using Segment’s Web SDK.

    "page": {
      "path": "/account",
      "referrer": "",
      "search": "",
      "title": "Your Account",
      "url": "https://www.example.com/account"
    },

However for iOS and Android, it won’t collect page information.

Moloco Commercial Media requires the page_id attribute for a PAGE_VIEW event. Using the Web SDK, the page_id can be associated with the path attribute. However for iOS/Android, Moloco Commercial Media recommends using the Page Identifier Token field.

The Page Identifier Token field accepts key:value pairs of strings that can identify the page. Stringification Logic is: {key}:{value}s concatenated by “;”

Moloco Commercial Media ignores the Page Identifier Token if page_id is passed, as page_id has a higher priority.

Here’s an example of a Page Identifier Token that could be tracked in a mobile app.

Say the input had the following schema:

    ...
      "event": "Product List Viewed",
      "vertical": "fruit"
    ...

and user chose the following mapping:

    // "event" represents the name of the event
    event: properties.event
    // "vertical" represents which vertical the event happened on
    vertical: properties.vertical

    // The combination of those two tokens can repsent
    // "Which action happened on which vertical"

The tokens are stringified into the following:

    "event:Product List Viewed;vertical:fruit"

The tokens are stringified in the format of the above example because they are key-value pairs concatenated by a semicolon (;).

if you decide to use the Page Identifier Token in your mobile app, reuse the same Page Identifier Token in place of page_id when calling Moloco’s APIs.

Mappings

In the Mappings tab, some fields are chosen by default if some common fields map to Moloco Event’s fields. If the mapped key does not exist in the input data, it won’t trigger an error. Instead, the mapping will not pass any value.

If you are using the default fields in a custom way, please confirm that your mapping meets Moloco’s requirements.

Default Mappings are not hard rules. They can be modified to your convenience.

Destination Settings

Setting Description
API Key Required.

The API key for the platform

Channel Type Required.

Type of channel, either APP or SITE. Defaults to SITE.

Platform ID Required.

ID of the platform

Platform Name

Name of the platform (default to the Platform ID)

Available Presets

Moloco MCM has the following presets:

Preset Name Trigger Default Action
Search Event type = "track" and event = "Products Searched"
Search
Page View Event type = "page" and properties.name != "Home" and properties.name != "Land"
Page View
Item Page View Event type = "track" and event = "Product Viewed"
Item Page View
Land Event type = "page" and properties.name = "Land"
Land
Add to Wishlist Event type = "track" and event = "Product Added to Wishlist"
Add to Wishlist
Home Event type = "page" and properties.name = "Home"
Home
Purchase Event type = "track" and event = "Order Completed"
Purchase
Add to Cart Event type = "track" and event = "Product Added"
Add to Cart

Available Actions

Build your own Mappings. Combine supported triggers with the following Moloco MCM-supported actions:

Mapping limits per destination

Individual destination instances have support a maximum of 50 mappings.

Purchase

Represents a user purchasing an item

Purchase is a Cloud action. The default Trigger is: type = "track" and event = "Order Completed"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items* Type: OBJECT

Item information list related to the event.

Revenue* Type: OBJECT

Revenue of the event

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority.

Shipping Charge Type: OBJECT

Shipping charge’s monetary amount in a specific currency.

Represents a user searching for an item

Search is a Cloud action. The default Trigger is: type = "track" and event = "Products Searched"

Click to show / hide fields

Add to Cart

Represents a user adding an item to their cart

Add to Cart is a Cloud action. The default Trigger is: type = "track" and event = "Product Added"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items* Type: OBJECT

Item information list related to the event.

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority.

Page View

Represents a user viewing a certain page that is pertinent to sequence-based ML model training (Ex. a user browsing sneakers)

Page View is a Cloud action. The default Trigger is: type = "page" and properties.name != "Home" and properties.name != "Land"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items Type: OBJECT

Item information list related to the event.

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”. Either page_id or page_identifier_tokens is required.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority. Either page_id or page_identifier_tokens is required.

Referrer Page ID Type: STRING

Similar to referrer in HTTP, this value indicates from which page the user came to the current page.

Home

Represents a user visiting a home page

Home is a Cloud action. The default Trigger is: type = "page" and properties.name = "Home"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items Type: OBJECT

Item information list related to the event.

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority.

Add to Wishlist

Represents a user adding an item to their wishlist

Add to Wishlist is a Cloud action. The default Trigger is: type = "track" and event = "Product Added to Wishlist"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items* Type: OBJECT

Item information list related to the event.

Revenue Type: OBJECT

Revenue of the event

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority.

Land

Represents a user visiting the client’s website from an external source (ex. Google Shopping)

Land is a Cloud action. The default Trigger is: type = "page" and properties.name = "Land"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items Type: OBJECT

Item information list related to the event.

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority.

Referrer Page ID* Type: STRING

Similar to referrer in HTTP, this value indicates from which page the user came to the current page.

Item Page View

Represents a user viewing an item page

Item Page View is a Cloud action. The default Trigger is: type = "track" and event = "Product Viewed"

Click to show / hide fields

Field Description
Event ID Type: STRING

Unique ID generated by the client to suppress duplicate events. The length should not exceed 128 characters.

Timestamp* Type: DATETIME

Timestamp that the event happened at.

User ID Type: STRING

User Identifier for the platform. The length should not exceed 128 characters.

Device Type: OBJECT

Device information of the event

Session ID Type: STRING

Identifier for tracking users regardless of sign-in status. The length should not exceed 128 characters.

Default Currency Type: STRING

The default currency value. Defaults to “USD”. If this is set, it will be used as a default currency value for items.

Items* Type: OBJECT

Item information list related to the event.

Page ID Type: STRING

A string value used to uniquely identify a page. For example: “electronics”, “categories/12312”, “azd911d” or “/classes/foo/lectures/bar”.

Page Identifier Tokens Type: OBJECT

Tokens that can be used to identify a page. Alternative to page_id with a lower priority.

Monitoring

Once the mappings are configured correctly, you can verify the flow of events from your source to Moloco’s destination in the Delivery Overview tab of your Moloco destination. If you correctly configured your destination, you should see a growing Successful delivery count.

Engage

You can send computed traits and audiences generated using Engage to this destination as a user property. To learn more about Engage, schedule a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Engage sets that value to false.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Real-time to batch destination sync frequency

Real-time audience syncs to Moloco Commerce Media may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

Setting Description
API Key
(required)
password. The API key for the platform
Channel Type
(required)
select. Type of channel, either APP or SITE. Defaults to SITE.
Platform ID
(required)
string. ID of the platform
Platform Name string. Name of the platform (default to the Platform ID)

This page was last modified: 11 Sep 2024



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account