Send requests to the user event API

You must follow the steps below to start sending API requests to the user event API.

Step 1. Reach out to your Moloco representative to initiate the integration.

Step 2. Send API requests to the Event API. Moloco uses these persistent identifiers to generate a single internal MCM identifier:

• user_id
• device.persistent_id

We recommended using persistent generated session ids in a first-party cookie or browser local storage and generating unique identifiers for web browsers or use the unique device identifiers for mobile devices in the persistent_id field. Customers should use their existing unique user IDs for the user_id field.

• user_idis your internal unique identifier for registered users.
• device.persistent_idis the UDID of the device used for the event.

For more information on identifiers used by Moloco MCM please Generating persistent identifiers

🚧

Caution

Customers should the same unique identifiers listed above inside their Decision API request parameters.

To send marketplace user events to Moloco Commerce Media, you must send a POST API request to the user event API with your platform ID as in the following example. Moloco will provide your {platform_name} and {platform_id}.

https://{platform_name}-evt.mcm-api.moloco.com/rmp/event/v1/platforms/{platform_id}/userevents

The request header must include your API key as in the following example. API keys are generated and managed in the Moloco Portal under Credential Management.

"Content-Type": "application/json"
"X-API-Key": "{api_key}"

🚧

Caution

Your request body must be in JSON object format. You can include the following properties in the request body. For more information, see the User Event API reference.

To enable API integration testing, Moloco provides two platform identifiers, one for testing, and one for actual ingestion. Using the test platform_id, you may send test requests and receive test responses. Your MCM representatives will provide you with the platform_ids during the initial onboarding.

The User Event API client GitHub repository contains detailed request format examples based on a code library implemented with JavaScript/TypeScript.

Sending ADD_TO_CART event

// This example is for reporting your events server-to-server (S2S).
import { client } from '../common/event-api-client';
import usParser from 'ua-parser-js';

const { session, headers } = req;
const ua = usParser(headers['user-agent']);

client.insertEvent({
  id: randomString(),
  eventType: 'ADD_TO_CART',
  timestamp: Date.now(),
  channelType: 'SITE',
  userId: session.user.id,
  device: {
    os: ua.os.name,
    osVersion: ua.os.version,
    model: ua.device.model,
    persistentId: ua.device.persistent_id,
  },
  items: [
    {
      id: product.id,
      price: product.salePrice
      quantity: product.quantity,
    },
  ],
  pageId: `CATEGORY_HOME_PAGE:${categoryId}`,
  referrerPageId: `PRODUCT_DETAIL_PAGE:${productId}`,
});

Sending PURCHASE event

client.insertEvent({
  id: randomString(),
  eventType: 'PURCHASE',
  timestamp: Date.now(),
  channelType: 'SITE',
  userId: session.user.id,
  device: {
    os: ua.os.name,
    osVersion: ua.os.version,
    model: ua.device.model,
    persistentId: ua.device.persistent_id,
  },
  items: products.map((product) => ({
    id: product.id,
    price: product.salePrice,
    quantity: product.quantity,
  })),
  revenue: {
    currency: 'USD',
    amount: totalAmount,
  },
  pageId: 'ORDER_SUMMARY_PAGE'
  referrerPageId: 'CART_PAGE',
});

Sending ITEM_PAGE_VIEW event

client.insertEvent({
  id: randomString(),
  eventType: 'ITEM_PAGE_VIEW',
  timestamp: Date.now(),
  channelType: 'SITE',
  userId: session.user.id,
  device: {
    os: ua.os.name,
    osVersion: ua.os.version,
    model: ua.device.model,
    persistentId: ua.device.persistent_id,
  },
  items: [
    {
      id: product.id,
      price: product.salePrice
      quantity: 1,
    },
  ],
  pageId: `PRODUCT_DETAIL_PAGE:${productId}`,
  referrerPageId: `CATEGORY_HOME_PAGE:${categoryId}`,
});