Data Export
X3M provides daily event reports, summarizing all the tracked events from your apps during the previous day. To receive these reports, you need to configure your storage credentials to allow X3M services to write data to your storage. Once set up, you will start receiving the events that we have tracked from your applications.
This page contains the instructions to start receiving once a day your X3M events, we currently support exports to buckets in Amazon S3 or Google Cloud Storage.
Events Description and Metrics
Every day we will be sending you the events we tracked for your apps during the previous day. On the bucket you gave us, you will find the data for each app in json zipped files in a folder with the date as a name, partitioned by hour. For example, if your app ID equals to 10 and you are waiting for the events from the first day of June, you will find them in a path like: 10/2023-06-01/event_hour=0/.
Inside each app’s folder, you will find a _SUCCESS file which indicates that this app’s data is completed for the date mentioned in the precedent folder. Each app’s data is independent, so you might find one’s data is completed while others are still being loaded to your bucket.
When analyzing your data, you will find different events with common and different properties.
Events List
- init: indicates that the user has initialized x3m sdk
- request: show that a user is requesting an ad to be shown.
- matched/unmatched_request: is the result of the previous request, which might have been filled (matched) or not(unmatched).
- impression: probably the most important event that indicates that the ad was successfully shown on the user's device. It contains the eCPM metric you can use to calculate your revenue.
- click: indicates that the ad was clicked.
Despite being different events, all of them share the same structure, so they are easy to process.The most important fields contained in the events data are:
Events Dictionary
- event_name: indicates the event name
- event_id: the id that makes it unique
- event_time: a date time to know when it was generated
- event_upload_time: a date time to know when we received the event, usually is almost the same as the event_time
- org_id: your organization id
- app_id: your app id
- app_version: your app version
- platform: android or iOS
- country: from which country it was sent
- ifa (optional): user identifier, depending on their device
- xifa: x3m users unique identifier.
- sdk_version: x3m’ssdkversion
- user_properties: unlike previous properties which are string or numeric fields, this key will be a json object containing more that one field.
- event_properties: contains all the properties that make each event_type different from the others. For example, you will find different keys for the matched/unmatched request event (waterfall_data, winning instance id, winner instance cpm) compared to are quest event.
Using all that information, you could easily calculate any business metric you want. For example, by counting the number of impression events you could know that metric for any time window you desire, you could divide by 1000 and sum the ecpm present on the event_properties from your impression events to calculate the revenue measured by any dimension you want.
Mapping Data
Beside the files containing the events’ data, you will be receiving another group of files inside the “mapping” key in your bucket. These files allow you to map the ids inside the events to the names you are used to seeing in X3M’s UI.
The files are in csv format and only contain the columns “id” and “name”, but we will be adding more columns in the near future.
While each day’s events are written in different folders and files in your bucket, the mapping data is always delivered in the same files. These files are updated every day before the events’ data is written in your bucket. However, the changes you might see in the mapping files will be the same ones you made during the previous day through the UI. If you have not made any changes, the files between those consecutive days will remain exactly the same.
Steps for Amazon S3
- To send you the events, your S3 bucket must have the right policy to allow us to write there. At the end of this document, you will find the policy that you need to apply (Please don’t forget to write your bucket name in the policy).
- Tell your account manager the name of the bucket you have configured to receive the events so that we can make our side configurations to start writing your data there.
- Wait until the next day and you will find on that bucket all your apps’ events we tracked for the previous day.
- If you need any other data beyond the previous day, let us know and we can work on that too.
AWS S3 Policy
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::804549073939:root"
},
"Action":[
"s3:AbortMultipartUpload",
"s3:DeleteObject",
"s3:GetObject",
"s3:ListBucket",
"s3:GetBucketLocation",
"s3:PutObject"
],
"Resource":[
"arn:aws:s3:::your-s3-bucket-name",
"arn:aws:s3:::your-s3-bucket-name/*"
]
}
]
}
Steps for Google Cloud Storage
-
In order to send you the events, we need you to configure your Google credentials to allow our services to write in your storage. We strongly recommend you create:
a. New storage: we recommend you create a storage dedicated only to receiving X3M raw events
b. New service account: create a new one that only allows you to read and write in the new bucket you have created
-
Once you have created them, please share your credentials and bucket name with your account manager. Wait until the next day and you will find on that bucket all your applications events we tracked for the previous day.
-
If you need any other data beyond the previous day, let us know and we can work on that too.
Google Credential Keys Example
{
“private_key_id”: “67fcd4fbaf134970c5015aa8de1c4436bd7”
"private_key_id": "'-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhkiG9wA==\n-----END
PRIVATE KEY-----\n",
“client_email”: “your-sa-email@this-is-an-example.iam.gserviceaccount.com”
}