Skip to content
Retidal Docs

Event mappings

Map your app's raw event names to Retidal's 17 standard events, so ad platforms and decisioning can act on them.

An event mapping links one of your project’s own event names (e.g. user_paid) to one of Retidal’s 17 standard events (e.g. PURCHASE). This mapping is what lets Ad platforms translate your business events into each platform’s native conversion event — without a mapping, an event has no standard-event identity and cannot be reported as a conversion to any platform.

Prerequisites

Section titled “Prerequisites”
  • The target standard event’s global definition id — list definitions with GET /api/event-definitions and note the id of the one you want to map to (e.g. PURCHASE). appEventName itself does not need to have been sent by the project before; the mapping is what gives that name meaning going forward.

Authentication

Section titled “Authentication”

Every endpoint on this page is a Management API call — host https://retidal.com, authenticated with the trackly_session cookie from a logged-in console user, not a project API key. See Authentication for the full model.

Listing mappings

Section titled “Listing mappings”
GET https://retidal.com/api/projects/{projectId}/event-mappings

Returns every mapping currently configured for the project — each entry names the app event name, the standard event it maps to, and its active/inactive status.

Console → Projects → Event Mappings shows the same list, with a search box and a create-mapping dialog.

Creating a mapping

Section titled “Creating a mapping”
GET https://retidal.com/api/event-definitions
POST https://retidal.com/api/projects/{projectId}/event-mappings

First find the target standard event’s definition id:

GET /api/event-definitions response (excerpt)
{
  "events": [
    { "id": "evtdef_9f2a1c", "code": "PURCHASE", "name": "Purchase", "category": "Monetization", "hasAmount": true }
  ]
}

Then create the mapping using that id as eventDefinitionId:

{
  "appEventName": "user_paid",
  "eventDefinitionId": "evtdef_9f2a1c",
  "isActive": true
}
201 Created
{ "mapping": { "id": "map_7c1b3e", "appEventName": "user_paid", "eventDefinitionId": "evtdef_9f2a1c", "isActive": true } }

POST /api/projects/{projectId}/event-mappings returns 404 if eventDefinitionId doesn’t match an existing event definition, and 409 if a mapping already exists for the same appEventName.

Deleting a mapping (optional)

Section titled “Deleting a mapping (optional)”
DELETE https://retidal.com/api/projects/{projectId}/event-mappings/{mappingId}

Removes a mapping outright. Once deleted, events carrying that app event name stop translating to any standard event — Ad platforms postback for that event name stops until a new mapping replaces it.

What this unlocks

Section titled “What this unlocks”

A configured mapping is the single dependency Ad platforms needs to translate your business event into a platform-native conversion — nothing else on that page works until the mapping exists.

Verify it worked

Section titled “Verify it worked”

Console → Projects → Event Mappings shows the mapping you just created, with the app event name and the standard event it points to. Equivalently, from a browser session already logged into the console (so the trackly_session cookie is sent automatically):

bash
curl -s https://retidal.com/api/projects/{projectId}/event-mappings \
  -H "Cookie: trackly_session=$SESSION_COOKIE"
# expect: 200 { "mappings": [...] } containing the mapping you just created, with
# your appEventName and eventDefinitionId

If it doesn’t work

Section titled “If it doesn’t work”

If a raw event name maps to the wrong (or no) canonical event — breaking the same postback-crediting chain Ad platforms depends on — work through Conversions failing.