Overview
This document defines the schema for the cohort long-form (CLF) data you'll send to Ktrl via S3. Use it as a reference when preparing your export.
Field requirements
All fields are required unless marked Optional. Optional fields are only optional if agreed with your implementation manager during onboarding. Otherwise, treat them as required.
Field | Type | Description |
Dimensions |
|
|
registration_date | date | The registration date of a cohort in the format YYYY-MM-DD. This is when a customer is registered for the service but not necessarily transacted |
activity_date | date | The activity date for a given cohort is in the format YYYY-MM-DD |
category_country | string | The value of the country pertaining to a segment. E.g. will contain values like US or AU |
category_platform | string | The value of the platform pertaining to a segment. E.g. will contain values like IOS or ANDROID |
category_channel | string | The value of the channel pertaining to a segment. E.g. Have to be one of the values Paid, Organic or Blended |
category_network | string | A column with the title category_network will contain values like Google Adwords, Facebook etc. |
category_opttype | string | Optional: A column with the title category_opttype will contain values like ROAS, CPI, CPE etc. |
category_campaign | string | A column for the campaign name
Values must not use the “|” (pipe) character, as this is reserved. |
Measures |
|
|
active_users | int | The number of unique users that have interacted with the product. This also includes users that have transactions occurring where they are not using the app themselves |
gross_revenue_[name] | float | The gross amount customers spent during transactions (e.g. in-app purchases). This definition should match up to what you use for your revenue budgets
You can provide multiple revenue types in different fields. E.g. you can provide gross_revenue_iap for in-app purchases and gross_revenue_ads for ad revenue
Standardised names to be used: gross_revenue_iap gross_revenue_ads -> Total revenue from ads gross_revenue_ads_banners gross_revenue_ads_interstitial |
net_revenue_[name] | float | Optional: If the margin varies noticeably by transaction, provide the net revenue for a more detailed analysis on margins |
marketing_spend | float | The total marketing spend. If you do not receive marketing spend per cohort per day, add the full value for the cohort where registration_date = activity_date and 0 where registration_date != activity_date |
paying_users | int | The number of unique users that spent money (this value must be less or equal to active_users) |
ad_users | int | Optional: The number of unique users that watched an ad (this value must be less or equal to active_users) |
transactions | int | The number of user transactions |
first_time_payers | int | Optional: The number of first-time payers |
ad_views | int | Optional: The number of ad views by users |
impressions_banners | int | Optional: The number of banner impressions |
impressions_rewarded | int | Optional: The number rewarded impressions |
impressions_interstitial | int | Optional: The number of interstitial impressions |
Categories, Values & Segments
Throughout the file specification, we use categories, category values, and segments.
Categories classify users by attributes like country, platform, or channel. Each category has values (e.g., country: US, UK, IT). Combining values across categories creates segments, such as US|ANDROID|PAID.
For more details, see our Introduction to Segmentation article. This is not required if Integrating with Ktrl.
Examples
registration_date | activity_date | category_country | category_platform | category_channel | active_users | gross_ revenue_ iap |
2023-01-01 | 2023-01-01 | US | ANDROID | PAID | 1068 | 534 |
2023-01-01 | 2023-01-02 | US | ANDROID | PAID | 503 | 498 |
2023-01-01 | 2023-01-01 | US | IOS | ORGANIC | 492 | 557 |
2023-01-01 | 2023-01-01 | GB | IOS | PAID | 492 | 557 |
Next steps
Once your data export is ready, head to CLF File Format & Delivery to set up the S3 integration with Ktrl.