It's a common case that you use a third-party system to store data about the event (registration, purchase, deposit, etc.) happening within the application. These events are not automatically tracked by the MMP, since it tracks the channel from where the users come. All the events users do are tracked in your system.
To send the events to Affise MMP and to the services the MMP integrated with (Facebook, for example, to optimize ad campaigns), use the guide below.
Events sending logic
The events should be sent with the event ID to Affise MMP to further register it in the system.
There are two requests to create an installation or event:
https://restapi.affattr.com/v1/external_data/add_simple_event - covers most of the necessary needs. GET request is preferred.
https://restapi.affattr.com/v1/external_data/add_event - has additional parameters. POST request is preferred.
Basic event creation method
This is a basic method to create an event:
https://restapi.affattr.com/v1/external_data/add_simple_event
?adid=7c21cab9-018d-1000-9861-000000000000
&event_name=CompleteRegistration
&API-KEY=<api-key>XML
You can do the same using a POST request:
curl --request POST \
--url https://restapi.affattr.com/v1/external_data/add_simple_event \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"adid": "7c21cab9-018d-1000-9861-000000000000",
"event_name": "CompleteRegistration"
}'
Also, you can use one more method for the same:
https://restapi.affattr.com/v1/external_data/add_event
?adid=7c21cab9-018d-1000-9861-000000000000
&event.affise_event_name=CompleteRegistration
&API-KEY=<api-key>
curl --request POST \
--url https://restapi.affattr.com/v1/external_data/add_event \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"adid": "7c21cab9-018d-1000-9861-000000000000",
"event": {
"affise_event_name": "CompleteRegistration"
}
}'
Examples
Create a new installation
You need to send app_id, first_open_time - the time (timestamp in seconds or milliseconds) the application was first opened and an available identifier that is used to send events, for example a gaid. The install is created if no such user device is found.
🔎 You can send this request for the system to create only one installation for the used identifiers. No duplicates are created.
https://restapi.affattr.com/v1/external_data/add_simple_event
?gaid=7c21cab9-018d-1000-9861-000000000000
&app_id=999
&first_open_time=1717611637000
&API-KEY=<api-key>
You can use multiple IDs and combine install with event:
https://restapi.affattr.com/v1/external_data/add_simple_event
?gaid=7c21cab9-018d-1000-9861-000000000000
&adid=7c21cab9-018d-1000-4689-000000000000
&user_id=7c21cad1-018d-1000-b4ca-000000000000
&app_id=999
&first_open_time=1717611637000
&event_name=CompleteRegistration
&API-KEY=<api-key>
Common cases
Using MMP identifiers is recommended:
https://restapi.affattr.com/v1/external_data/add_simple_event
?affise_device_id=7c21cab9-018d-1000-9861-000000000000
&random_user_id=7c21cad1-018d-1000-b4ca-000000000000
&event_name=CompleteRegistration
&API-KEY=<api-key>
When using Google and Apple IDs, indicate the application ID:
https://restapi.affattr.com/v1/external_data/add_simple_event
?idfa=7c21cab9-018d-1000-9861-000000000000
&app_id=999
&event_name=CompleteRegistration
&API-KEY=<api-key>
https://restapi.affattr.com/v1/external_data/add_simple_event
?gaid=7c21cab9-018d-1000-9861-000000000000
&app_id=999
&event_name=CompleteRegistration
&API-KEY=<api-key>
⚠️ If necessary, you can use MMP click_id, but it's not recommended since different users may have the same click_id.
https://restapi.affattr.com/v1/external_data/add_simple_event
?click_id=7c21cab9-018d-1000-9861-000000000000
&event_name=CompleteRegistration
&API-KEY=<api-key>
If necessary, you can use external click_id, but it's not recommended since different users may have the same external click_id.
https://restapi.affattr.com/v1/external_data/add_simple_event
?pub_click_id=7c21cab9018d
&event_name=CompleteRegistration
&API-KEY=<api-key>
Some events require additional parameters, for example purchase event to send to Facebook:
https://restapi.affattr.com/v1/external_data/add_simple_event
?affise_device_id=7c21cab9-018d-1000-9861-000000000000
&event_name=Purchase
&p_price=100
&p_quantity=2
&p_revenue=200
&p_currency=USD
&API-KEY=<api-key>
https://restapi.affattr.com/v1/external_data/add_event
?affise_device_id=7c21cab9-018d-1000-9861-000000000000
&event.affise_event_name=Purchase
&event.affise_parameters.affise_p_price=100
&event.affise_parameters.affise_p_quantity=2
&event.affise_parameters.affise_p_revenue=200
&event.affise_parameters.affise_p_currency=USD
&API-KEY=<api-key>
The data types for affise_parameters can be int, float or string. The system converts the type to the required one:
curl --request POST \
--url https://restapi.affattr.com/v1/external_data/add_event \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"affise_device_id": "7c21cab9-018d-1000-9861-000000000000",
"event": {
"affise_event_name": "Purchase",
"affise_parameters": {
"affise_p_price": 100.1,
"affise_p_quantity": 2,
"affise_p_revenue": "200.2",
"affise_p_currency": "USD",
}
}
}'
You can use your custom type and custom parameters, but some functionality is not available for them. For time, use timestamp in seconds or milliseconds:
curl --request POST \
--url https://restapi.affattr.com/v1/external_data/add_event \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"affise_device_id": "7c21cab9-018d-1000-9861-000000000000",
"random_user_id": "7c21cad1-018d-1000-b4ca-000000000000",
"event": {
"affise_event_name": "MyCustomName",
"affise_event_timestamp": 1717611637000,
"affise_event_user_data": "text for export to report",
"affise_parameters": {
"affise_p_currency": "USD",
"affise_p_price": "6",
"external_event_name": "external custom name"
}
}
}'
Description of parameters
parameter for add_event | parameter for add_simple_event | type | required | description |
affise_device_id | affise_device_id, device_id | uuidv1 (string) | one of them, recommended | A unique user’s device identifier generated inside the SDK |
random_user_id | random_user_id, user_id | uuidv4 (string) | one of them | Random unique UserID in the SDK |
gaid_adid | gaid_adid, gaid | string | one of them | Google gaid, collisions are possible if several installations occur with one gaid. If the device was found by affise_device_id, gaid will be set for this device, if it was missing previously |
adid | adid, idfa | string | one of them | Apple adid, collisions are possible if several installations occur with one adid. If the device was found by affise_device_id, adid will be set for this device, if it was missing previously |
click_id | click_id | uuidv4 (string) | one of them | Сlick attribution, collisions are possible if several installations occur with one click |
pub_click_id | pub_click_id | string | one of them | Сlick external system (click performance refers to them), collisions are possible if several installations occur with one click |
app_id | app_id | int | no | Application ID, you can find it in your personal account. Required to create an install. Recommended to use with gaid and adid to identify the application correctly. |
first_open_time | first_open_time | timestamp (int) | no |
|
event.affise_event_id |
| uuidv4 (string) | no | Unique event identifier, use this field if you need to change the event or its parameters. Do not use this parameter if you are not sure of its necessity!!! |
event.affise_event_name | affise_event_name, event_name, event | string | yes | Can be predefined (see description of SDK) or custom. CamelCase only |
event.affise_event_timestamp |
| timestamp (int) | no | Time (in seconds or milliseconds) when the event occurred, use this field if the event occurred in the past and it is important. Do not use this parameter if you are not sure of its necessity ⚠️ |
event.affise_event_user_data |
| string | no | Data on events that cannot be parametrized for use - at the request of the client. |
event.affise_event_first_for_user |
| bool | no | Flag indicating that the event occurred for the first time. Do not use this parameter if you are not sure of its necessity ⚠️ |
event.affise_parameters.* |
| string | no | You can use any custom parameters, but some of the functionality for such parameters will not be available |
event.affise_parameters.affise_p_* | event.affise_parameters.affise_p_* affise_p_*, p_* | string | no | Event parameters, see the complete list of predefined parameters in the SDK documentation. The most important parameters are given below |
event.affise_parameters.affise_p_price | p_price | string | no | Parameter is used in external integrations, but is not used to calculate money in reports |
event.affise_parameters.affise_p_revenue | p_revenue | string | no | Parameter is used in external integrations and is used to calculate money in reports |
event.affise_parameters.affise_p_currency | p_currency | string | no | Currency, default USD |
Please contact the Affise Customer Support team regarding all raised questions via the e-mail: [email protected].