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 RAW DATA (ie. a complete list of individual installs/events/purchases originated in a certain time frame).
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/raw/installs Content-Type: text/csv Authorization: Bearer eyJhbGciOiJIUzI12345InR5cCI [...] [CSV content]
- 3 separate endpoints are available, for feeding different types of performance data:
- https://upload.bubbleye.com/raw/installs
- https://upload.bubbleye.com/raw/iapRevenue
- https://upload.bubbleye.com/raw/events
- To upload retention, simply report the “app launch” event for the relevant device (use “app_launch” as event name)
2. Upload frequency
- The expected upload frequency depends on the circumstances:
- If data is being uploaded regularly, as a replacement for realtime postbacks: at least daily, ideally hourly, with no strict requirement.
- If data is being uploaded one-off (typically for historical data ingestion before starting new campaigns), frequency is of course not an issue: make sure to inform your Bubbleye AM as soon as the data is uploaded and we’ll ensure it was ingested successfully
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 by a certain device in a certain geo at a certain time, through a certain specific event), 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/purchases/events 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
- The file must follow the standard CSV specifications: https://tools.ietf.org/html/rfc4180
- Granularity: each record in the CSV must refer to each individual instance of installs/events/purchases generated.
- No matter what type of data is being uploaded, 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 install/event/purchase, 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 install/event/purchase, 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 purchase being uploaded (in ISO format, UTC time zone): YYYY-MM-DDTHH:MM:SS.sss). Contact your Bubbleye AM if additional formatting options are needed.
[This column may be left blank when uploading installs: in that case, ‘created_at’ will be used instead]- Example: 2020-10-10T01:33:42.432
- created_at: The date and time when the event or purchase was generated (in ISO format, UTC time zone): YYYY-MM-DDTHH:MM:SS.sss). Contact your AM if additional formatting options are needed.
- Example: 2020-10-12T05:35:15.123
- Note: if you don’t have precise timestamps for each install/event/purchase, please consider using our aggregated data upload API instead.
- creative_type: type of the creative responsible for the install/event/purchase being uploaded. 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: The ID assigned by the network to the creative responsible for the install/event/purchase
- Example: “xyz123”
- creative_name* [ May be left empty ] : The name of the creative responsible for the install/event/purchase
- Example: “Mighty Warrior”
- ifa* [ May be left empty IF t_uid is provided ] : Apple’s IDFA or Google’s GAID, identifying the device that generated the install/event/purchase being uploaded. It’s highly recommended to populate this column, which allows the Kraken to operate PPU-based optimizations.
- t_uid * [ May be left empty IF ifa is provided ] : MMP-specific unique user ID
- Note: if you don’t have the IFA or t_uid for a certain event, please fabricate a unique ID for that device or consider using our aggregated data upload API instead, so as to ensure different entries related to different devices in the same dimensions won’t be considered as one.
- value: depends on the type of data being uploaded:
- if the data being uploaded relates to installs, this field will be ignored [ May be left empty ]
- if the data being uploaded relates to IAP revenue, this is the amount of revenue generated by the purchase event, at the indicated ‘created_at’ time
- if the data being uploaded relates to events, this is the name of the event being triggered at the indicated ‘created_at’ time
- For ‘app launch’ events to calculate retention, enter “bb_app_opened” as event name
- network: Name of the network the campaign was run on. Please consult with your Bubbleye AM for a full list of names.
