Bulk performance upload is a way for the Kraken to ingest campaign performance data as an alternative to realtime postbacks for each individual app event.
This document specifically refers to bulk upload of Aggregated Data (ie. installs/events/revenue originated in a certain time frame across all users of a certain publisher, grouped by a time unit of choice (e.g. all the installs/events/revenue occurred in a certain hour or day).
If you’d like to report installs/events/revenue with higher granularity, please consider using our Raw Data upload API.
1. Endpoints and Authentication
- Data is provided through CSV file upload via REST API
- Authentication happens through Bearer token, to be provided by Bubbleye upon project start. E.g.:
POST https://upload.bubbleye.com/aggregated/installs Content-Type: text/csv Authorization: Bearer eyJhbGciOiJIUzI12345InR5cCI [...] [CSV content]
- 4 separate endpoints are available, for feeding different types of performance data:
- https://upload.bubbleye.com/aggregated/installs
- https://upload.bubbleye.com/aggregated/events
- https://upload.bubbleye.com/aggregated/retention*
- https://upload.bubbleye.com/aggregated/iapRevenue
- https://upload.bubbleye.com/aggregated/adRevenue*
2. Upload frequency
- The expected upload frequency depends on the type of data being uploaded:
- Regular uploads of Installs/Events/In-App Purchase Revenue (as a replacement for realtime postbacks): hourly frequency
- Regular uploads of Retention or Ad Revenue: daily frequency
- If data is being uploaded one-off (typically for historical data ingestion before starting new campaigns), just make sure to inform your Bubbleye AM once the data is uploaded and we’ll ensure it was ingested successfully
- Note that every upload will result in NEW RECORDS being added into Kraken’s DB (if data related to a certain HOUR or DAY needs to be re-uploaded or amended, please contact your Bubbleye AM and they’ll assist with data deletion and re-upload).
3. Data updates/amendments
These APIs assess the uniqueness of a certain entry based on the concatenation of all dimensions. As a consequence, the following update options are supported:
- Updating values: if data related to a certain set of dimensions is uploaded multiple times (e.g. re-uploading the revenue generated through a certain publisher in a certain geo / time unit), the latest value will supersede (overwrite) any previously uploaded value for those same dimensions. This allows you to amend previously uploaded values for certain installs/events/revenue as long as you indicate a different value for the exact same dimensions.
- Updating dimensions: on the contrary, in situations where you’d like to amend a certain dimension (ie. because previously filled in erroneously) – e.g. the wrong ‘geo’ or ‘creative’ had been filled in a previous revenue upload – then the faulty rows will have to be deleted before being re-uploaded: please contact your Bubbleye AM and they will assist with data deletion and re-upload
4. Data format
- Expected one .CSV file containing all the desired data to be ingested for the given time frame. Note that all columns are required, though some of them may be left blank as indicated below.
- The file must follow the standard CSV specifications: https://tools.ietf.org/html/rfc4180
- Granularity: each record in the CSV shall refer to an aggregate count of installs/events/revenue generated in the time slot indicated in the ‘created_at’ column (see below).
- No matter what type of data is being uploaded, or its granularity, the following CSV columns are accepted:
- network: Name of the network the campaign was run on. Please consult with your Bubbleye AM for a full list of names.
- Examples: ironSource, Unity, AppLovin
- app: store ID (Android package name or iTunesID) of your app or game
- Examples: com.rovio.angrybirds, id880047117
- campaign_name: Name of the campaign responsible for generating the installs/events/revenue, exactly as reported by the attribution partner (MMP).
- Example: AppLovin_campaignA
- geo: Two letter country code of the targeted country. Capitalized.
- Examples: US, DE, JP
- pub_id: The ID of the publisher (sometimes called sub-publisher or Site ID) responsible for generating the installs/events/revenue, as identified by the Network. This value should be sent as a string.
- Examples: 123456, abc123
- installed_at: The date and time of the user’s install responsible for the event or revenue being uploaded (in ISO format and UTC time zone). Hourly granularity is required: YYYY-MM-DDTHH.
[This column may be left blank when uploading installs: in that case, ‘created_at’ will be used instead]- Example: 2020-10-10T16
(this value should be used for all installs occurred between 4pm and 4.59pm on the 10th of October, 2020 UTC)
- Example: 2020-10-10T16
- created_at: The date and time when the event or revenue was generated (in ISO format and UTC time zone). Granularity depends on the data being uploaded:
- [Installs], [Events] or [In-App Purchase Revenue]: hourly (YYYY-MM-DDTHH).
- Example: 2020-10-12T17
(this value should be used for all installs/events/purchases occurred between 5pm and 5.59pm on the 12th of October, 2020 UTC)
- Example: 2020-10-12T17
- [Retention] or [Ad Revenue]: daily (YYYY-MM-DD)
- Example: 2020-10-12
(this value should be used to report the total ad revenue originated between 00:00 and 23.59 on the 12th of October, 2020 UTC)
- Example: 2020-10-12
- Contact your AM if different granularity is needed
- [Installs], [Events] or [In-App Purchase Revenue]: hourly (YYYY-MM-DDTHH).
- creative_type: type of the creative responsible for the installs/events/revenue generated at the indicated ‘created_at’ time. Must be either of the following:
- “image” (for image-only ads, such as banners or static interstitials)
- “video” (for all video ads, with or without complementary start- or end-card images)
- “playable” (for html5 interactive ads)
- creative_id* [ May be left empty ]: The ID assigned by the network to the creative responsible for the installs/events/revenue generated at the indicated ‘created_at’ timeExample: “Mighty Warrior”
- Example: “xyz123”
- creative_name* [ May be left empty ]: The name of the creative responsible for the installs/events/revenue generated at the indicated ‘created_at’ time
- Example: “Mighty Warrior”
- value: depends on the type of data being uploaded
- if [Installs]: this column shall be left blank
- if [Events]: this is the name of the event being triggered at the indicated ‘created_at’ time
- if [Ad Revenue] or [In-App Purchase Revenue]: this is the amount of revenue generated in the selected combination of the other columns, at the indicated ‘created_at’ time
- if [Retention]: this is the amount of retained users on the specified ‘created_at’ date, among those users who installed on the ‘installed_at’ date
- count: the expected value depends on the type of data being uploaded:
- if [Installs]: this is the count of installs occurred in the specific 1-hour slot
- if [Events]: this is the count of occurrences of the specific event name, in the indicated ‘created_at’ time
- if [Retention] or [Ad Revenue]: this column shall be left blank
- if [In-app Purchase Revenue]: this is the count of unique paying users in the selected combination of the other columns, at the indicated ‘created_at’ time
- network: Name of the network the campaign was run on. Please consult with your Bubbleye AM for a full list of names.
5. Response
Response content will contain error messages related to the CSV sent. Some common issues are:
- Datetime formatting, check that your string for datetime matches the specified formats above.
- Quoting: Especially for some names, quoting may be required to workaround unexpected commas
