Using the API to call Jixie tracker

Introduction

In some case it is not possible to integrate Jixie tracker using our Javascript tag. In that case it is possible to use our tracker API. However it necessitates more work on the partner side as he will be responsible for the whole integration.

This article describes how to implement such integration. However it won't describe all the parameters that have to be sent to the API. Those parameters are already described in the following articles:

Jixie has a development environment that can be used to test the API integration. If the data is wrongly sent to the production environment, the data will be dismissed and not taken into account.

How does it work?

The generic process of the API is the following:

  1. use a stored Jixie client ID, or call an API to generate one

  2. send the parameters to the tracking API

The first phase is very important. Without having a Jixie client ID, it is not possible for us to associate the call to a client. This phase is done only once, and then the partner needs to store the client_id on the device of the user (similar to a cookie). Calling the client ID generator each time the user connects leads to a lack of tracking.

The second phase is more standard. It consist in putting in place the different parameters in a proper JSON payload and call the POST API with this payload.

Getting the Jixie Client ID

There are 2 use cases:

  • when we know the user email

  • when the user email is unknown

User email unknown

There are 2 calls to perform:

  • a first one to generate a new Jixie ID

  • a second one to associate the Jixie ID with the mobile ID (IDFA)

Method

Endpoint

Parameters

Response

GET

{base_url}/api/newid

None

{
  "client_id":"123456",
}

GET

{base_url}/api/usersync

?idlist=<jixie_id retrieved from previous call>:jx,<device ID>:device

{
  "client_id":"123456",
}

The first call will generate a temporary client ID. The second call will check if there is already an existing client ID associated with this device ID. If yes then the resulting client_id from the second might be different from the result of the first call.

It is important to store the client ID resulting from the second call only.

The validity of the client ID is 3 months. It means that after 3 months we need to call the second endpoint again to eventually replace the client ID that was stored.

User email known

It is very similar to when the user email is unknown. However, when calling the second endpoint you need to add the SHA 256 encoded email to the parameters like:

?idlist=<jixie_id retrieved from previous call>:jx,<device ID>:device,<SHA256 encoded email>:emailsha

Important: this call has to be made after any authentication of the user

Summary of the decision tree

  • Call only once {base_url}/api/newid the first time the user loads the app

  • First time the user loads the application or every 3 months or when the user log-in to the application call {base_url}/api/usersync

    • if the user is not logged: send the Jixie ID and the device Id

    • if the user is logged: send the Jixie ID, the device Id and the SHA256 encoded email

Calling the tracker API

Method

Endpoint

Payload

Response

POST

{base_url}/sync/prod

JSON

{
"success":1,
"clientip":"x.x.x.x",
"isp":"ISP"
}

The different parameters of the JSON:

Parameter

Format

Description

accountid

String

The ID of the account of the partner (you). This is provided by your account manager. Without this information your calls will be ignored.

client_id

String

The client ID retrieved during the previous phase (if not called yet), or retrieved from the storage of the device.

deviceid

String

The device ID of the end user.

partnerid

String

The client ID in the partner system. For example the ID that is gotten from SSO.

payload

JSON object

An object containing the parameters of the call (e.g. the different parameters to provide for each page). It is the same parameters as defined here (for publishers) and here (for merchants), except for accountid, email and actions (we already have them as direct parameters of the call to the API).

referer

String

The deep link to the page or screen the action has been made (the URI of the page or screen in other words)

domain

String

The name of the application

sha256mail

String

The SHA256 encoded email of the user when available.

action

String

The type of action of the user. See the different possibilities of action here (for publishers) and here (for merchants).

Example of simple payload:

{
    "accountid":"123456",
    "referer":"https://www.website.com/page.html", // considering universal links
    "action":"viewhome",
    "payload":{},
    "client_id":"123456",
    "deviceid":"qwerty",
    "sha256mail":"1584342519-123456",
    "domain":"My awesome application"
}

Example of article visit

{
    "accountid":"123456",
    "referer":"https://www.website.com/page.html", // considering universal links
    "action":"visit",
    "payload":{
 		"itemid":"54fg4",
 		"keywords":["key1","key2"], 
 		"title":"Amazing article",
 		"description": "This is a description",
        "category":"travel",
        "published_date":"2022-01-26T13:51:50"
    },
    "client_id":"123456",
    "deviceid":"qwerty",
    "sha256mail":"1584342519-123456",
    "domain":"My awesome application"
}

Example of more complex payload:

{
    "accountid":"123456",
    "referer":"https://www.exmaple.com/page.html",
    "action":"viewitem",
    "payload":{
        "itemid":"123456",
        "price":"1000",
        "availability":"instock",
        "currency":"IDR"
    },
    "client_id":"123456",
    "deviceid":"qwerty",
    "sha256mail":"1584342519-123456",
    "domain":"My awesome application"
}

Please find below other related articles.