Events API (server-to-server)

In complex use cases, where the user journey includes 3rd party platforms/applications (e.g. Telegram chatbot, Mobile Sandboxed WebApp, Discord, Telegram games), the best way to report on user engagement and conversion events is directly from your server to your Addressable account using a secure API.

Request Structure

The Addressable API has a request structured with the following fields:

• An endpoint url: https://tag.adrsbl.io/events/prod_standard_stage/p.png

• Two parameters:

  1. is_conversion Use is_conversion=true, When you wish to designate an event as a conversion event for it to be recognized as such across all counters that track attributed conversions in our product. Use is_conversion=false for all other events.

  2. data data is a base64-wrapped JSON parameter that contains event metadata according to the table below.

Parameter Name	Is Mandatory	Type	Value
tid	Mandatory	String	Addressable pixel ID which can be found under 'Settings' in your Addressable account.
page_url	Mandatory	String	The page URL that generated the event can also be represented simply as a string.
event_name	Mandatory	String	The name of the event as you’d like it to be displayed on our platform
timestamp	Mandatory	Int	Timestamp of the event in UTC
timezone_name	Mandatory	String	User reported timezone for time offset calculation. E.g America/New_York
timezone_offset	Mandatory	Int	The number of seconds in which the user timezone is offset from UTC time.
referrer	Optional	String	The page URL which referred to the page that generated the event. It may be an empty string.
chain_id	Optional	String	If the blockchain ID is known to you on the page where the event was triggered, please specify it here. For example, for the Ethereum chain, send "0x1".
extension_provider	Optional	String	Name of wallet provider if known to you when the event is triggered. E.g “MetaMask”.
properties	Optional	List of Jsons	See below for instructions on how to utilize the properties field.

Based on the table above, a request could be formulated in the following manner:

Typical Request Example

https://tag.adrsbl.io/events/prod_standard_stage/p.png?is_conversion=false&data=eyJ0aWQiOiAiYzI3ZTdjN2QxODA2NDgxY2I2ZDEwZDk1OTczNGNmZjYiLCAiZXZlbnRfbmFtZSI6ICJ0ZXN0dG9tZXIzIiwgInBhZ2VfdXJsIjogInRlbGVncmFtIiwgInJlZmVycmVyIjogIiIsICJ0aW1lc3RhbXAiOiAxNzIzMzQ0NjQ4LCAidGltZXpvbmVfbmFtZSI6ICJBbWVyaWNhL05ld19Zb3JrIiwgInRpbWV6b25lX29mZnNldCI6IDI0MCwgInByb3BlcnRpZXMiOiBbeyJuYW1lIjogInBhcmFtMSIsICJ2YWx1ZSI6ICJ2YWx1ZTEifSwgeyJuYW1lIjogInBhcmFtMiIsICJ2YWx1ZSI6ICJ2YWx1ZTIifSwgeyJuYW1lIjogInBhcmFtM19ub192YWx1ZSJ9XX0%3D

Requests sent to our servers must be URL-encoded. Refer to how URL encoding works for more detailed information.

Include"Content-Type": "application/json" header in the request when sending it.

Event Properties

In the context of utilizing the Addressable Pixel, our software manages the definition of user sessions and user IDs. Conversely, the responsibility for managing S2S events lies with you.

To improve your comprehension of user behavior, make use of the properties field to record key/value parameters that aid in understanding user behavior. This field comprises a list of JSON objects, where each key/value pair represents a specific property and its corresponding value. Refer to the example below for guidance on accurate properties reporting:

"properties": [{"name": "customer", "value": "mycustomer"},
               {"name": "username", "value": "Billy Bob"},
               {"name": "free_plan"}]

In the example provided, three parameters were established. The first two parameters consist of both a name and a value, while the third parameter only includes a name.

Code Example

Please refer to the following Python code snippet demonstrating how to generate a request to our servers:

import json
import base64
import requests

data = json.dumps({"tid": "<your tid goes here>",
                   "event_name": "test",
                   "page_url": "telegram",
                   "referrer": "",
                   "timestamp": 1723344648,
                   "timezone_name": "America/New_York",
                   "timezone_offset": 240,
                   "properties": [{"name": "customer", "value": "mycustomer"},
                                  {"name": "username", "value": "Billy Bob"},
                                  {"name": "free_plan"}]})
                                  

params = {"data": base64.b64encode(data.encode())}
headers = {
    "Content-Type": "application/json"
}
url = 'https://tag.adrsbl.io/events/prod_standard_stage/p.png?is_conversion=false'
res = requests.get(url, params=params, headers=headers)

For technical assistance and troubleshooting, contact us at [e-mail]