REST API Integration

Overview

This document provides a comprehensive guide for integrating with Metica's REST API. It covers prerequisites, endpoints, request headers, authentication, payload structure, and advanced usage examples for event ingestion, personalised offers, smart configurations, and useful event data.

---

Prerequisites

Before initiating API requests, the Metica onboarding team will provide the following:

• API Key: Used to authenticate requests.

• Application ID: Used to identify the target application.

These credentials will be referred to as API_KEY and APP_ID throughout this document.

---

API Conventions

Base Endpoint

All API requests should be directed to the following base endpoint:

https://api-gateway.prod-eu.metica.com

---

Request Headers

Metica's API uses JSON for both request and response payloads. Additionally, some GET endpoints may use parameters formatted as application/x-www-form-urlencoded query strings in the URL.

Header Name	Expected Value
Content-Type	application/json; charset=utf-8

---

Authentication

Metica's API uses API keys for authentication and authorisation. Include your API key in the X-API-KEY header for all API requests.

Example Using curl

curl --url https://api-gateway.prod-eu.metica.com/... \
  --header 'X-API-KEY: <API_KEY>'

---

HTTP Status Codes

Metica's API utilises standard HTTP status codes to indicate the outcome of an operation.

Code	Description
200	Successful Request - The request was processed successfully.
202	Accepted - The payload was accepted, and the request was completed successfully.
400	Bad Request - The request is invalid (e.g., malformed syntax or missing parameters).
401	Unauthorized - The request lacks valid authentication credentials.
403	Forbidden - The API key does not have sufficient permissions for the requested operation.
404	Not Found - The requested resource could not be located.
429	Too Many Requests - The rate limit has been exceeded; retry after a delay.
5xx	Internal Server Error - The server encountered an unexpected condition that prevented it from completing the request.

In cases of client errors (e.g., 400), responses may include a payload describing the invalid part of the request to assist in troubleshooting.

---

Event Ingestion

The event ingestion endpoint is the primary method for submitting user in-app behaviour data to Metica.

Endpoint

/ingest/v1/events

---

Request Headers

Header Name	Expected Value
X-API-KEY	Your unique API key.
Content-Type	application/json; charset=utf-8

---

Request Payload

The payload should include a list of events, with each event containing key-value pairs representing individual user actions.

Example Payload

{
  "events": [
    {
      "userId": "u1",
      "appId": "<APP_ID>",
      "eventTime": "2023-11-28T15:19:07.458Z",
      "eventType": "purchase",
      "offerId": "a",
      "totalAmount": 1
    },
    {
      "userId": "u2",
      "appId": "<APP_ID>",
      "eventTime": "2023-11-28T15:24:07.000Z",
      "eventType": "login"
    }
  ]
}

---

Example Request Using curl

curl --request POST \
  --url https://api-gateway.prod-eu.metica.com/ingest/v1/events \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <API_KEY>' \
  --data '{
    "events": [
      {
        "userId": "u1",
        "appId": "<APP_ID>",
        "eventTime": "2023-11-28T15:19:07.458Z",
        "eventType": "purchase",
        "offerId": "a",
        "totalAmount": 1
      },
      {
        "userId": "u2",
        "appId": "<APP_ID>",
        "eventTime": "2023-11-28T15:24:07.000Z",
        "eventType": "login"
      }
    ]
  }'

---

Response Codes

Code	Description
202	The request was processed successfully.
4xx	Client error; refer to the HTTP Status Codes section for details.
5xx	Server error; refer to the HTTP Status Codes section for details.

Mandatory Event Attributes

Attribute	Type	Description
userId	string	Unique user identifier.
eventType	string	Type of event, e.g., purchase, login.
appId	string	Unique application identifier matching APP_ID.

---

Personalized Offers

The personalised offers endpoint enables you to fetch offers tailored to specific users.

Endpoint

/offers/v1/apps/<APP_ID>

---

Request Parameters

Name	Type	Description	Example
placements	string	A list of placements for which offers should be returned. If not provided, offers for all placements will be returned.	?placements=main,shop

---

Example Request Using curl

curl -X POST 'https://api-gateway.prod-eu.metica.com/offers/v1/app/<APP_ID>?placements=p1,p2' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'X-API-KEY: <API_KEY>' \
--data '{
  "userId": "abc",
  "deviceInfo": {
    "store": "AppStore",
    "timezone": "America/Denver",
    "appVersion": "1.4.5",
    "locale": "en-US"
  },
  "userData": {
    "level": 10,
    "inventory": {
      "potion": { "quantity": 30 }
    },
    "gemBalance": 51
  }
}'

---

Response Example

{
  "placements": {
    "p1": [
      {
        "offerId": "offer_abc",
        "creativeId": "creative_large_bundle_94",
        "items": [
          {
            "id": "potion",
            "quantity": 1
          }
        ],
        "price": 50,
        "discount": 0.23,
        "currencyId": "gems"
      }
    ],
    "p2": []
  }
}

---

Smart Config

Description

The Smart Config endpoint allows you to fetch dynamic and personalised configurations.

• The set of configuration keys can be restricted through the keys parameter.

• If no keys are provided, the entire configuration will be returned.

In a similar manner to the Personalised Offers endpoint, the request payload can include user attributes that influence the choice of configurations.

Endpoint

/config/v1/apps/<APP_ID>

---

Request Headers

Header Name	Expected Value
X-API-KEY	Your unique API key.
Content-Type	application/json; charset=utf-8

---

Request Parameters

Name	Type	Description	Example
keys	string	A list of configuration keys to fetch. If not provided, all configuration keys will be returned.	?keys=cfg1,cfg2

---

Example Request Using curl

curl -X POST 'https://api-gateway.prod-eu.metica.com/config/v1/app/<APP_ID>?keys=cfg1,cfg2' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'X-API-KEY: <API_KEY>' \
--data '{
  "userId": "abc",
  "deviceInfo": {
    "store": "AppStore",
    "timezone": "America/Denver",
    "appVersion": "1.4.5",
    "locale": "en-US"
  },
  "userData": {
    "level": 10,
    "inventory": {
      "potion": { "quantity": 30 }
    },
    "gemBalance": 51
  }
}'

---

Response Example

{
  "cfg1": 1.23,
  "cfg2": ["a", "b", "c"]
}

---

Useful Event Data

Offer Events

Event	Description
metrics.display	Dispatched when an offer is displayed.
metrics.purchase	Dispatched when an offer is purchased.
metrics.interaction	Dispatched when a user interacts with an offer.

---

Install Event

The Install event should be dispatched when the application is installed. Attributes can include acquisitionSource, device, and OS.

---

Login Event

The Login event should be dispatched for each user session. Attributes can include device, OS, and appVersion.

---

Player State Updates

Overwrite Current State

{
  "userId": "string",
  "appId": "string",
  "eventType": "meticaUserStateUpdate",
  "userStateAttributes": { "key": "value" }
}

Partial State Update

{
  "userId": "string",
  "appId": "string",
  "eventType": "meticaUserAttributesChange",
  "userStateAttributes": { "key": "value" }
}

---