Track Conversions in Mobile Apps

In native mobile applications the Poltio Tag (the JavaScript snippet used to track conversions on websites) is not available, so your app sends conversion events directly to the Poltio Conversion API over HTTPS.

If you display Poltio widgets in a WebView or in-app browser, see Using Poltio Widgets in Mobile Applications first.

Required

Authentication

All requests require a Bearer JWT token issued for your Poltio account. Send it in the Authorization header:

Authorization: Bearer {token}

You can get your token from Poltio Panel under Settings → API Tokens. Requests with a missing or invalid token are rejected with 401 Unauthorized. Keep your token safe.

POST/sdk/conv/events

Submit conversion events

Send a single conversion event as a JSON body. Two event types are supported: ViewContent and Purchase. A successful request returns 204 No Content. The full OpenAPI specification is available in the Poltio Conversion API reference.

Attributes

Name
event_name
Type
string
Description
Required. Either ViewContent or Purchase.
Name
event_time
Type
integer
Description
Unix timestamp in seconds of when the event happened.
Name
user_data
Type
object
Description
Required. Must contain at least one of puid or external_id (a string, or a list of strings where the first value is used). If both are provided, puid takes priority.
Name
event_source_url
Type
string
Description
Required for ViewContent. The full URL of the product page the user landed on from the widget recommendation, including the psource and poltio_session_id query parameters. psource is always poltio; poltio_session_id comes from the recommended product link in the widget.
Name
custom_data
Type
object
Description
Required for Purchase — contains the purchase details (see below). Not used for ViewContent and can be omitted.

Linking events to the same user

puid and external_id are not issued or stored by Poltio — your app generates them. Typically you generate a unique value (e.g. a UUID) once when your mobile application is installed, persist it on the device, and send the same value with every event. Since it never changes for that installation, Poltio can link user activity over time (e.g. a ViewContent followed later by a Purchase).

Name
puid
Type
string
Description
Poltio User ID. A unique identifier generated by your app on install and stored on the device. It stays the same for the lifetime of the installation.
Name
external_id
Type
string
Description
An identifier from your own system. Use it when puid is not available.

Request

POST

/sdk/conv/events

let body: [String: Any] = [
  "event_name": "Purchase",
  "event_time": Int(Date().timeIntervalSince1970),
  "user_data": ["puid": "8b3f1b9a-3e74-4d7c-9b0a-24e4a1d7b9dd"],
  "custom_data": [
    "value": 123.45,
    "currency": "TRY",
    "order_id": "ORDER-123",
    "contents": [["id": "product123", "quantity": 1, "value": 123.45]]
  ]
]

var request = URLRequest(url: URL(string: "https://sdk.poltio.com/sdk/conv/events")!)
request.httpMethod = "POST"
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: body)
URLSession.shared.dataTask(with: request).resume()

Response

204 No Content

ViewContent events

Send a ViewContent event only when a user finishes the widget and clicks a recommended product. The user is then directed to a recommended product detail page (PDP) or product listing page (PLP) — that view is the ViewContent event.

event_source_url is required and must be the URL of that product page, including the psource and poltio_session_id query parameters. The widget appends both to the recommended product button's link: psource is always poltio, and poltio_session_id identifies the widget session — read it from that link and use it in your conversion events. custom_data is not used for ViewContent — you can omit it.

ViewContent request body

{
  "event_name": "ViewContent",
  "event_time": 1764975551,
  "event_source_url": "https://example.com/page?psource=poltio&poltio_session_id=2b6c7f6b-0e32-4cf8-8e18-79c7fdbbc8c1",
  "user_data": { "puid": "8b3f1b9a-3e74-4d7c-9b0a-24e4a1d7b9dd" }
}

Purchase events

Send a Purchase event on every checkout success — do not wait for or depend on a ViewContent event. Poltio matches purchases with earlier ViewContent events through puid/external_id, so it can tell which purchases came through the Poltio widget. custom_data is required and holds the purchase details:

Name
value
Type
number
Description
Required. The total monetary value of the purchase.
Name
currency
Type
string
Description
Currency code, up to 3 letters (e.g. USD, TRY).
Name
order_id
Type
string
Description
A unique identifier for the order.
Name
contents
Type
array
Description
An array of purchased items, each with id, quantity, value, and optionally category and name.

Purchase request body

{
  "event_name": "Purchase",
  "event_time": 1762902353,
  "user_data": { "puid": "8b3f1b9a-3e74-4d7c-9b0a-24e4a1d7b9dd" },
  "custom_data": {
    "value": 209.85,
    "currency": "TRY",
    "order_id": "ORDER-123",
    "contents": [
      { "id": "product123", "quantity": 1, "value": 123.45, "name": "Running Shoes" },
      { "id": "product456", "quantity": 2, "value": 29.95, "name": "Socks" },
      { "id": "product789", "quantity": 1, "value": 26.50, "name": "Water Bottle", "category": "Accessories" }
    ]
  }
}

Error responses

Status	Meaning
`204`	Event accepted and processed.
`400`	Bad request — missing fields, unsupported `event_name`, or invalid JSON. The plain-text body states the reason, e.g. `missing user_data.puid or user_data.external_id`.
`401`	Unauthorized — missing or invalid Bearer token.
`405`	Method not allowed — only `POST` is supported.

If you use a custom domain, replace https://sdk.poltio.com with your subdomain address in the endpoint URL.