Integrate Events data

User event API Integration

MOLOCO RMP's User Event API can be used to deliver user event data to MOLOCO. API calls are possible both on the server side and on the client side, but server side integration ensures faster API connection speed and stability.

User event API Key

Accessing the API requires an API key. MOLOCO provides two types of API keys.

Test API key for testing
Production API key for an actual ingestion

Please request the API keys through the MOLOCO representative.

API Document

📘
Please send the user event data in the specified format. Detailed format and requirements are described in the following document.

Overview

User Event API allows you to send your events to the MOLOCO RMP event service. It requires an API key to authenticate and event data must be sent in the specified format.

How to use it

Contact your business manager to initiate the integration.
Moloco will provide you an API key, say {api_key}, which will be used in the API to identify your user account.
You would send requests to the User Event API to post your events to the MOLOCO RMP event service.
Any of the identifiers (user_id, session_id, device.advertising_id, and device.unique_device_id) is not required but one of them should be present in a request.

API Endpoint: Post Event

This part describes how to post your events to the MOLOCO RMP event service.

HTTP Request Endpoint

Use the POST method. You should put your platform ID at {platform}.

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

Request Header

Note that you should put an X-API-Key header with {api_key} value.

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

Request Body

Use a JSON object for the request body. Below is the schema of the object.

For detailed specifications of the payloads, please refer to the API reference.

Sample request body

You can check the request format examples in detail through the code library implemented with JavaScript/TypeScript in Github repository below.

📄 Github repo of JavaScript/TypeScript library for RMP User Event API

Also, you can refer to the Customer Tools Github repository for sample Python scripts.

Send 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,
    ip: req.socket.remoteAddress,
  },
  items: [
    {
      id: product.id,
      price: product.salePrice
      quantity: product.quantity,
    },
  ],
  pageId: `CATEGORY_HOME_PAGE:${categoryId}`,
  referrerPageId: `PRODUCT_DETAIL_PAGE:${productId}`,
});

Send 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,
    ip: req.socket.remoteAddress,
  },
  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',
});

Send 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,
    ip: req.socket.remoteAddress,
  },
  items: [
    {
      id: product.id,
      price: product.salePrice
      quantity: 1,
    },
  ],
  pageId: `PRODUCT_DETAIL_PAGE:${productId}`,
  referrerPageId: `CATEGORY_HOME_PAGE:${categoryId}`,
});

Handling errors

import { client } from '../common/event-api-client';
import { v1 } from '@moloco-rmp/event-api-client';

client.insertEvent({ ... })
  .catch((error) => {
    console.error(error.message);
    if (error instanceof v1.errors.InternalServerError) {
      ...
    } else if (error instanceof v1.errors.BadRequestError) {
      ...
    } else if (error instanceof v1.errors.ForbiddenError) {
      ...
    } else if (error instanceof v1.errors.NetworkError) {
      ...
    } else if (error instanceof v1.errors.NotFoundError) {
      ...
    } else if (error instanceof v1.errors.UnauthorizedError) {
      ...
    } else if (error instanceof v1.errors.UnknownError) {
    }
  });

❗️
Please note that there is a lead time of injecting real-time event data of about 2 weeks for model training. Therefore, it is recommended to integrate event data first.