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

• Three 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. Note: You can have multiple conversion events with this attribute set to true.

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

Parameter Name	Is Mandatory	Type	Value	Usage
tid	Mandatory	String	Addressable pixel ID which can be found under 'Settings' in your Addressable account.	For associating events with your tenant
page_url	Mandatory	String	The page URL that generated the event can also be represented simply as a string.	For tracking users as they move between different pages of your website / funnel.
event_name	Mandatory	String	The name of the event as you’d like it to be displayed on our platform	For identifying user events that lead to actions
timestamp	Mandatory	Int	Timestamp of the event in UTC	Ability to filter by time
timezone_name	Mandatory	String	User reported timezone for time offset calculation. E.g America/New_York	Ability to filter by the user's time
timezone_offset	Mandatory	Int	The number of seconds in which the user timezone is offset from UTC time.	Ability to filter by the user's time
referrer	Optional	String	The page URL which referred to the page that generated the event. It may be an empty string.	For makreting channel drilldown, to understand where the traffic is coming from
address	Optional	String	The wallet address of the tracked user if known to you on the page where the event was triggered.	A wallet address is one of the identifiers used to track user events within your system. Addressable also enriches wallets with on-chain data, offering a comprehensive view of your users.
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".	Ability to filter by blockchain and track user actions on various blockchains
extension_provider	Optional	String	Name of wallet provider if known to you when the event is triggered. E.g “MetaMask”.	The ability to filter by wallet provider is available on our interface.
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=eyJ0aWQiOiAiPHlvdXIgdGlkIGdvZXMgaGVyZT4iLCAiZXZlbnRfbmFtZSI6ICJleGFtcGxlX2V2ZW50IiwgInBhZ2VfdXJsIjogInRlbGVncmFtIiwgInJlZmVycmVyIjogImh0dHBzOi8vdC5tZSIsICJ0aW1lc3RhbXAiOiAxNzIzMzQ0NjQ4LCAidGltZXpvbmVfbmFtZSI6ICJBbWVyaWNhL05ld19Zb3JrIiwgInRpbWV6b25lX29mZnNldCI6IDI0MCwgImV4dGVuc2lvbl9wcm92aWRlciI6Ik1ldGFNYXNrIiwgImFkZHJlc3MiOiAiMHgwMDBjRDI3RjEwZEZGQUM3MzIwMTI1OEVBQTM5MjVjMDQ1MjA1MUEwIiwgImNoYWluX2lkIjogIjB4YTRiMSIsICJleHRlbnNpb25fcHJvdmlkZXIiOiAiTWV0YU1hc2siLCAicHJvcGVydGllcyI6IFt7Im5hbWUiOiAidXNlcl9pZCIsICJ2YWx1ZSI6ICJ1dWlkLXZhbHVlLWdvZXMtaGVyZSJ9LCB7Im5hbWUiOiAicGFyYW0yIiwgInZhbHVlIjogInZhbHVlMiJ9LCB7Im5hbWUiOiAicGFyYW0zX25vX3ZhbHVlIn1dfQ%3D%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.

1. Request Headers Please use the following headers to pass user information to our servers. Refer to the table below:

Header	Is Mandatory	Value	Usage
Content-Type	Mandatory	application/json	For proper functioning of server-to-server API
Accept-Language	Optional	Use the original user's Accept-Language header and not your server's header	For drilldown and filtering based on user attributes: i.e languages
User-Agent	Optional	Use the original user's User-Agent header and not your server's header	For drilldown and filtering on user's OS type, Browser Type, Platform etc.
X-Forwarded-For	Mandatory	User original IP address	extract country information for each session. In compliance with GDPR and SOC2 regulations, IP addresses are retained for no more than one week. Country data, once extracted, is stored per user_id for your breakdown use.
X-Requested-With	Optional	User mobile referrer app	For drilldown and filtering - identification of the user orgin app before landed on your app (mobile referrer)

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": "example_event",
                   "page_url": "https://app.example.com/test-tomer?a=1&b=2&c=3",
                   "referrer": "https://app.example.com/",
                   "timestamp": 1730538892,
                   "timezone_name": "America/New_York",
                   "timezone_offset": 240,
                   "extension_provider":"MetaMask",
                   "address": "0x000cD27F10dFFAC73201258EAA3925c0452051A0",
                   "chain_id": "0xa4b1",
                   "properties": [{"name": "user_id", "value": "uuid-value-goes-here"},
                                  {"name": "param2", "value": "value2"},
                                  {"name": "param3_no_value"}]}

params = {"data": base64.b64encode(data.encode())}

headers = {
    "Content-Type": "application/json",
    "Accept-Language": "en-US,en;q=0.9",
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
    "X-Forwarded-For": “1.1.1.1”,
    "X-Requested-With": "io.metamask"}

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]