Set up self-attribution data delivery

Use this option if your app integrates Apple's AdServices · Opens in a new tab framework and your team will supply attribution data directly.

4 steps
English / 简体中文
No BrightLake sign-in needed to read

Start setup Open official guide ↗

If you opened this guide from a form, return to the original tab to keep your unsaved changes.

4 steps

Setup steps

Before you begin

For the person who can change settings in the named platform.

Who does what

Your development team confirms AdServices integration. Operations coordinates the aggregate CSV handoff and report review.

What to have ready

An iOS app that integrates AdServices and can obtain Apple Ads attribution results.
An agreed aggregate CSV route, with event or USD revenue data separated as required.

This diagram explains the setup process. It does not confirm authorization, a live integration, or received data.

Confirm AdServices integration
Check that your iOS app integrates AdServices and can obtain Apple Ads attribution results. Your confirmation reports this setup; it does not run or verify your app.
Arrange report delivery
The supported route is an operator-assisted aggregate CSV import. Selecting API delivery records a request, not an available customer endpoint.
Prepare the report fields
Follow the public self-attribution guide for cohort dates, campaign mapping and cumulative event or USD revenue columns. AdServices alone does not supply in-app events or revenue.
Align timezones and event definitions
Before using the data for performance assessment, agree with operations on the timezone, field definitions, delivery frequency, your system's exact event names and any existing delivery arrangements.

Confirm completion and next steps

What to check

The cohort dates, campaign mapping, event or USD revenue fields and timezone are agreed.
Operations verifies imported rows and report values; an import receipt alone is not proof of usable data.

What happens next

Contact BrightLake to coordinate the data handoff and verify the result. Reading this guide does not create an integration or submit your application.

Tell BrightLake

Self-attribution report integration

The supported route is an operator-assisted aggregate report import. Prepare a report and arrange import with your account team. There is no documented customer endpoint for automatic event delivery. Selecting API delivery records a request, not an active integration.

CSV header templates

These downloads contain headers only, not customer data. Start with an authorized test export. Replace signup_completed with your exact event name and agree on a reporting window. Use separate event and revenue files.

One event, cumulative through day offset 7

Cohort Day,Campaign Id,signup_completed - count - day 7

Download event header template

USD revenue at day offsets 0, 2 and 6

Cohort Day,Campaign Id,Users,revenue - sum - day 0,revenue - sum - day 2,revenue - sum - day 6

Download revenue header template

1. Prepare a supported file

Use UTF-8 CSV without a byte-order mark (BOM), with headers in the first row. The file must be no larger than 50 MB. Event imports require CSV so the operator can select a detected day column. The backend can read the first XLSX worksheet, but the event-import screen cannot detect its day columns. Use plain numeric cells and YYYY-MM-DD dates.

2. Match the app and ad account

Cohort Day (or date) is the installation cohort date. Each row needs a valid date and Campaign Id. Campaign name is a fallback only when it uniquely identifies a campaign in the selected ad account. The system derives the app from the existing Apple Ads campaign mapping, not an app column. Prepare one app/ad-account scope at a time and have the team confirm its mapping. Unknown or wrong-account campaigns are skipped. If no campaigns match, the import fails.

3. Keep one level of aggregation

Optional headers include Users (also Install or Installs), Adset Id (also Ad Set Id), Adgroup name (also Ad Group Name or Adset name), and Keywords. Supply cumulative aggregates, not individual user events. Blank numeric cells become zero; duplicate matching rows are added together. Do not mix totals with their detail rows. Exclude personal or device identifiers, advertising costs and calculated ratios. Unknown columns do not change the destination app or currency.

4. Use one exact event and one agreed window

Use the exact event header pattern: event_name - count - day N. An optional trailing - partial is accepted but does not prove data maturity. Include one event family per file; do not mix events or combine event and revenue columns. The operator selects a day present in the file. Day 7 means cumulative results through offset 7. Each exact event name has one reusable metric slot per app/ad account. Changing its selected day changes that metric's window, rather than creating a parallel window. Keep the agreed window stable. Put explanations in onboarding or the handoff, not in the event name.

5. Export revenue in USD

Import writes USD without currency conversion. Do not supply non-USD amounts or expect a currency column to convert them. Use revenue - sum - day N headers. Day offsets 0, 2, 6, 13 and 29 map to t0, t3, t7, t14 and t30 revenue windows. Event offset 7 is not revenue t7 (offset 6). A summary revenue column writes only a total, not every day window. The largest revenue day present supplies the cumulative cohort value.

6. Agree on the timezone before exporting

The team can label the import ORTZ (the Apple Ads account reporting timezone), UTC or BJ (Asia/Shanghai). Your cohort dates and totals must already use that timezone. Import does not convert timestamps or redistribute values across calendar days. Reconcile using the same cohort date, timezone and reporting window.

7. Understand corrections and duplicates

Each upload creates a new import; files are not deduplicated by content. Reimporting matching rows updates their values, but omitted rows are not deleted. Duplicate rows within one file are added together. Record the file, scope, reporting window and receipt so the team can reconcile corrections before retrying. Do not change an event's window to create another metric.

8. Arrange the operator import

Use the secure handoff channel agreed with your account team. An authorized operator selects the linked customer, Apple Ads ad account and timezone in Admin's import screen. They select the AppsFlyer-format adapter, revenue or event-metric mode, day and file. The adapter identifies a file format; it does not mean you use AppsFlyer or need an Adjust integration. The operator needs import permission. Do not share application login credentials or internal service keys.

9. Verify the result, not only the receipt

Start with a small authorized test export for a known campaign and date. The operator checks job status and import history, then compares written rows and totals with your export for the same app, account, cohort date and timezone. Queued means accepted for processing, not usable data. A completed Admin job can still contain a partial import. Inspect missing campaigns and rows written, resolve rejected mappings, confirm the exact event metric and window, then read back report values. Repeat a controlled correction to confirm update behavior. Commercial approval and Performance readiness checks still apply.

Automatic API delivery needs a separate integration

A customer-facing delivery URL requires a deployed versioned collection route, app/tenant-scoped credentials and permissions, and defined payload and app/account mapping. It also needs cohort, timezone, window, amount and currency rules; durable receipts and errors; and tested idempotency, replay and correction behavior. The team must demonstrate the path from data production to storage and report readback. Internal import APIs and design proposals are not customer endpoints. Contact your account team to assess this dependency; do not send data to an assumed postback address.

This guide describes the current aggregate file-import implementation. It does not certify provider authorization, customer data, automatic collection or a production integration.

All guides

Need help?

Stuck on a step? Contact the BrightLake team.