Apple AdServices Attribution API実装ガイド｜attributionToken・payload差分・ATT影響を正しく読むiOS計測
Apple Search Adsで獲得したユーザーを正しく計測しようとして、公式リファレンスのattributionToken()やAdServices Attribution APIにたどり着いたものの、「トークンを取ってからどこに送れば良いのか」「返ってくるpayloadの各フィールドが何を意味するのか」「ATTを拒否されたユーザーでは何が変わるのか」が英語の断片情報に散らばっていて、実装の全体像が掴めない――そんな悩みを抱えていませんか。日本語圏の記事は「概念・運用の解説」か「2021年で止まった英語の実装コード」に二極化していて、両者を橋渡しする実装ガイドがほとんど存在しないのが実情です。
この記事では、attributionToken()でトークンを取得し、api-adservices.apple.comのエンドポイントへPOSTして、返ってきたpayload JSONを復号・パースするまでの一連の流れを、実装者の目線で日本語で通しで解説します。あわせて、standard payloadとdetailed payloadのフィールド差分、ATTの許可・拒否がpayloadの中身に及ぼす影響、24時間TTLや初回nullといった実装で必ず詰まる落とし穴、そしてSKAdNetworkやAdAttributionKitとの役割分担までを、広告運用者が判断すべき論点に翻訳しながら整理します。
結論を先に言えば、AdServices Attribution APIは「Apple Search Adsの成果を、MMPを噛ませず自社サーバーだけでも読める」希少な仕組みです。ただし生payloadを正しく読むには、フィールドの意味・ATTとの関係・エラーハンドリングを理解しておく必要があります。本記事を最後まで読めば、自前計測の最小構成を設計し、どこを外注し、どこを内製で握るべきかの判断軸まで持ち帰れます。
目次
- AdServices Attribution APIの全体像とiAd廃止・SKAdNetworkとの役割分担
- attributionToken()でトークンを取得しApple APIへ送るまでの実装
- 返却されるpayload JSONの全フィールドと意味を読み解く
- standard payloadとdetailed payloadの差分をフィールド単位で比較する
- ATTの許可状態がpayloadの中身をどう変えるか
- 実装でつまずくポイントと対処
- MMPを使わず自社でpayloadを受けて計測する最小構成の設計
- まとめはAdServices payloadを正しく読むための要点
- まずは無料で広告アカウント診断を
AdServices Attribution APIの全体像とiAd廃止・SKAdNetworkとの役割分担
AdServices Attribution APIは、Appleが提供する広告アトリビューションの仕組みのうち、主にApple Search Ads（Apple広告）経由のインストールを、決定論的（deterministic）に計測するためのAPIです。かつて存在したiAd Frameworkが廃止された後の後継として位置づけられ、iOS 14.3以降で利用できるAdServicesフレームワークを通じて、アプリ側でトークンを取得し、Appleのサーバーへ問い合わせることでキャンペーン情報を得られます。SKAdNetworkがネットワーク経由の匿名ポストバックで「集計値」を返すのに対し、AdServicesはアプリ内でトークンを取り、そのユーザー個別の流入元をJSONで受け取れる点が決定的に異なります。
まず押さえておきたいのは、この3つの仕組みが競合するものではなく、取得できるデータの性質と対象が違うという点です。AdServicesはApple Search Adsに限定される代わりに、campaignIdやkeywordIdまで含んだ粒度の高い情報を、ユーザー単位で自社サーバーへ持ち込めます。一方でSKAdNetworkとその後継であるAdAttributionKitは、Apple Search Ads以外のネットワーク（Meta、TikTok、独自メディアなど）を含む横断的な計測を、プライバシー保護のために集計・遅延・匿名化された形で扱います。「どのデータをどちらで取るか」を最初に切り分けておかないと、二重計上や取りこぼしが起きます。
実務では、Apple Search Adsのキーワード別・キャンペーン別の獲得効率を細かく見たいならAdServices、それ以外の媒体を含めた純増効果やインストール総量を測りたいならSKAdNetwork/AdAttributionKit、という役割分担が基本になります。両者は排他ではないため、同じインストールがAdServicesとSKAdNetworkの双方に現れることがあり、レポート上の数値差（いわゆるデータ乖離）の一因にもなります。この乖離を「バグ」と誤解して原因調査に時間を溶かすケースは非常に多いため、設計段階で「AdServicesはApple Search Adsの真値、SKAdNetworkは別軸の集計」と役割を明文化しておくことが重要です。
もう一つ理解しておきたいのは、AdServicesが返すのは「Apple Search Ads経由でインストールされたという事実とその流入元」であって、インストール後の課金や継続といったLTV系の指標そのものではないという点です。payloadから得たキャンペーン・キーワードのIDを、自社アプリ内で計測しているアクティブ率や課金データと突き合わせて初めて、「どのキーワードから来たユーザーが定着し収益を生んでいるか」まで見えてきます。AdServicesは獲得の入口を正確に押さえるための仕組みであり、その後ろにある自社の行動計測とセットで設計してこそ、Apple Search Adsの費用対効果を本当の意味で評価できます。この前提を押さえておくと、payloadに過剰な情報を期待して肩透かしを食らうこともなくなります。
| 仕組み | 対象媒体 | データ粒度 | 取得経路 | 主な用途 |
|---|---|---|---|---|
| AdServices Attribution API | Apple Search Ads（Apple広告）のみ | ユーザー単位・キャンペーン/キーワードまで | アプリ内でトークン取得→自社/Apple APIへPOST | ASAの獲得効率をキーワード粒度で見る |
| SKAdNetwork | 全ネットワーク横断 | 集計・匿名（コンバージョン値のみ） | ネットワーク→Apple→ポストバック | プライバシー配慮下の総量・純増把握 |
| AdAttributionKit | 全ネットワーク（SKANの後継） | 集計・匿名（再エンゲージメント対応） | ポストバック（Web to Appも対応） | 次世代の匿名アトリビューション |
本記事の主題はあくまでAdServices、なかでも「生payloadを自分でデコードして正しく読む」という実装一次情報に絞ります。SKAdNetworkやAdAttributionKitの制度整理、postbackの読み方、ATTにまつわる運用オペレーションの誤解を解く観点については、別記事で運用視点から詳しく整理しています。iOS計測の全体像を運用者目線で先に押さえておきたい場合は、次の記事を先に読んでおくと本記事の位置づけがより明確になります。
attributionToken()でトークンを取得しApple APIへ送るまでの実装
AdServices Attribution APIの実装は、大きく「トークン取得」と「トークンをエンドポイントへPOSTしてpayloadを受け取る」の2ステップに分かれます。トークン取得はアプリ側（Swift/Objective-C）で完結し、payloadの取得はそのトークンをapi-adservices.apple.com/api/v1/へPOSTすることで行います。POST先へトークンをそのままリクエストボディに載せると、Appleがそれを解釈してJSON形式のpayloadを返す、という素直な設計です。ここが理解できていれば、あとはエラーハンドリングとタイミングの問題に集約されます。
トークン取得のコード自体は数行で済みます。AdServicesフレームワークをインポートし、AAAttributionクラスのattributionTokenメソッドを呼ぶだけです。取得したトークンは文字列で、有効期限は発行から24時間です。この24時間という制約は後述するトラブルの温床になるため、取得直後にpayload取得まで一気に進めるのが原則になります。以下は最小構成のSwiftコードで、トークン取得からPOST、レスポンスのJSONパースまでを通しで示したものです。
| ステップ | 処理内容 | 実行場所 | 注意点 |
|---|---|---|---|
| 1. トークン取得 | AAAttribution.attributionToken() を呼ぶ | アプリ（端末） | シミュレータ不可・24時間で失効 |
| 2. POST送信 | 取得トークンをText本文でPOST | アプリ or 自社サーバー | Content-Typeはtext/plain |
| 3. レスポンス受信 | 200でJSON payload・404はデータ未生成 | 受信側 | 404はリトライで待つ |
| 4. JSONパース | attribution/campaignId等を読む | 受信側 | キーの出現条件に注意 |
実装で意外と見落とされがちなのが、POST先へ送る際のヘッダー設定です。リクエストボディはトークン文字列そのもので、Content-Typeはtext/plainを指定します。JSONで包んで送ると弾かれるため、生のトークンをボディに載せる点を間違えないようにしてください。レスポンスが200で返ればボディにJSONのpayloadが入っており、そこから各フィールドを読み解いていきます。トークンをアプリから直接送るか、いったん自社サーバーに渡してサーバー側からPOSTするかは設計次第ですが、後者のほうがリトライ制御やログ保全がしやすく、実務では推奨されます。
なお、CTV視聴からモバイルインストールまでをまたいで計測する設計や、アプリ計測の実装・評価まわりの考え方については、TVer×Adjustを題材にした実装ガイドでも近い論点を扱っています。AdServices単体ではなく、アプリインストール計測を横断的に設計したい場合の参考になります。
返却されるpayload JSONの全フィールドと意味を読み解く
api-adservices.apple.comから200で返ってくるpayloadは、Apple Search Adsのアトリビューション情報を含むJSONオブジェクトです。ここで返るキーの意味を1つずつ理解しておくことが、計測ロジックを正しく組む出発点になります。既存の日本語記事は「clickDateの有無」といった一言で済ませていることが多いのですが、実際にはattribution・orgId・campaignId・conversionType・adGroupId・countryOrRegion・keywordId・adId・clickDateといった複数のキーが返り、それぞれに意味と出現条件があります。
最も重要なのはattributionというブール値のキーです。これがtrueなら、そのインストールがApple Search Ads経由であると判定されたことを意味し、falseなら広告経由ではない（オーガニックなど）と判断できます。falseの場合、campaignIdやkeywordIdといった詳細キーは返らないか意味を持たないため、まずこのattributionフラグで分岐するのが計測ロジックの基本形です。ここを見ずにcampaignIdだけを読もうとすると、オーガニック流入を広告成果に誤計上してしまいます。
attributionがtrueの場合、orgId（広告アカウントの組織ID）、campaignId（キャンペーンID）、conversionType（DownloadかRedownloadか）、adGroupId（広告グループID）、countryOrRegion（国・地域）、keywordId（キーワードID）、adId（広告ID）などが返ります。これらは数値IDが多く、そのままでは人間が読めないため、Apple Search Ads Campaign Management APIやレポートAPIと突き合わせて、キャンペーン名やキーワード文字列に変換して初めて意味を持ちます。payloadは「IDの束」であり、名称解決は別APIとの照合が前提という点を設計に織り込んでおく必要があります。
payload主要フィールドの意味
- attribution：ASA経由かどうかのブール値。まずここで分岐するのが鉄則
- orgId：広告アカウントの組織ID。レポートAPIとの紐付けに使う
- campaignId：キャンペーンID。名称は別APIで解決
- conversionType：Download（新規）かRedownload（再DL）か
- adGroupId／keywordId／adId：広告グループ・キーワード・広告のID
- countryOrRegion：配信された国・地域コード
- clickDate：クリック日時。detailedでのみ返る（後述）
実務でつまずきやすいのは、conversionTypeの解釈です。DownloadとRedownloadを区別せずに新規獲得としてカウントすると、既存ユーザーの再インストールを新規CVに混ぜてしまい、CPIやCPAが実態より良く見えてしまいます。特に再インストールが多いアプリでは、この区別を計測ロジックに入れておくかどうかで数字が大きく変わります。payloadを受けたら、attributionでの一次分岐に加えて、conversionTypeでの二次分岐まで実装しておくのが正確な計測の条件です。
また、これらのIDを自社サーバーで受けて管理画面やBIツールに流し込む場合、サーバーサイドでの計測基盤の設計が品質を左右します。計測欠損を減らすサーバーサイド計測の考え方は、サーバーサイドGTMを題材にした記事でも詳しく触れています。AdServiceのpayloadを自社データ基盤へ統合する際の設計思想として参考になります。
standard payloadとdetailed payloadの差分をフィールド単位で比較する
AdServices Attribution APIのpayloadには、返る情報量の異なる2つのモードがあります。標準的に返るstandard payloadと、より詳細な情報を含むdetailed payloadです。多くの記事はこの差を「詳細版のほうが情報が多い」と一言で流しますが、実装者にとって重要なのは「どのフィールドがどちらに含まれるか」をキー単位で把握することです。ここを理解していないと、standardしか返らない状況でclickDateを前提にした計測ロジックを組んでしまい、本番で値が取れずに破綻します。
フィールド単位で見ると、attribution・orgId・campaignId・conversionType・adGroupId・countryOrRegion・keywordId・adIdといった基本的なIDはstandardでも返ります。一方でdetailedになると、clickDate（クリック日時）が追加され、その日時が分単位に丸められた形で返るのが大きな違いです。この分単位の丸めはプライバシー保護の一環で、秒単位の精緻な時刻は取得できません。クリックからインストールまでのタイムラグ分析をしたい場合はdetailedが必要になりますが、その粒度は「分単位」であることを前提に設計する必要があります。
detailed payloadを取得できる条件には制約があり、ATTの許可状況や配信の設定に依存します。つまり「detailedを指定すれば必ず詳細が返る」わけではなく、条件を満たさない場合はstandard相当の内容に縮退することがあります。計測ロジックは「detailedが返らない前提」でも動くよう、clickDateの欠損を許容する作りにしておくのが安全です。detailedの有無で処理が分岐するなら、キーの存在チェックを必ず入れてください。
| フィールド | standard | detailed | 備考 |
|---|---|---|---|
| attribution | 返る | 返る | ASA経由判定のブール値 |
| orgId | 返る | 返る | 組織ID |
| campaignId | 返る | 返る | キャンペーンID |
| conversionType | 返る | 返る | Download/Redownload |
| adGroupId | 返る | 返る | 広告グループID |
| keywordId | 返る | 返る | キーワードID |
| adId | 返る | 返る | 広告ID |
| countryOrRegion | 返る | 返る | 国・地域 |
| clickDate | 返らない | 返る（分単位丸め） | タイムラグ分析に必要 |
この差分を実装に落とす際のコツは、standardで必ず取れるIDを計測の主軸に据え、detailedのclickDateはあくまで「取れたら使う補助情報」として扱うことです。clickDateを主キーやCV判定の必須条件にしてしまうと、standardしか返らないケースで計測が止まります。IDベースでキャンペーン・キーワードの成果を集計し、タイムラグ分析はdetailedが取れたサブセットで別途行う、という二段構えにしておくと堅牢です。
ATTの許可状態がpayloadの中身をどう変えるか
AdServices Attribution APIを実装するうえで最も誤解されやすいのが、ATT（App Tracking Transparency）との関係です。運用者向けの記事では「詳細は許可時のみ」と一文で流されることが多いのですが、実装者としてはもう一段踏み込んで、ATTの許可・拒否でpayloadの何がマスクされ、何が残るのかを理解しておく必要があります。ここを曖昧にしたまま計測ロジックを組むと、ATT拒否ユーザーの成果を丸ごと取りこぼしたり、逆に取れないはずのデータを前提にしてエラーを出したりします。
重要な前提として、AdServices Attribution APIはATTの許可がなくても基本的なアトリビューションを返せる点があります。これはSKAdNetworkと同様、Apple自身が広告主とアプリの関係を仲介するファーストパーティ的な仕組みだからです。ATTはあくまでIDFAを用いたサードパーティ間のトラッキングに同意を求める枠組みであり、Appleが自社広告（Search Ads）の成果を返すこと自体はATTの許可を必須としません。したがって、campaignIdやkeywordIdといった基本的なpayloadは、ATTを拒否したユーザーでも取得できるのが原則です。
一方で、ATTの許可状況はdetailed payloadで返る情報の粒度に影響します。ATTを許可したユーザーではより詳細な情報（clickDate等）まで取得しやすくなり、拒否したユーザーでは詳細が縮退したり、より粗い粒度になったりします。計測ロジックはATT許可・拒否の双方でIDベースの計測が回るよう分岐させ、詳細情報はオプトインしたユーザーのボーナスとして扱う設計が現実的です。ATT拒否をもって「計測できない」と諦めるのは誤りで、Apple Search Adsの基本成果はしっかり残ります。
ATTとpayloadの関係で押さえる論点
- 基本のアトリビューション（campaignId等）はATT拒否でも取得できる
- ATTはIDFAによるサードパーティ追跡の同意であり、Apple自社広告の計測とは別軸
- detailedの詳細粒度はATT許可状況の影響を受けやすい
- ATT拒否を「計測不能」と誤解して成果を捨てないこと
- 計測ロジックは許可・拒否の両方でIDベース計測が回る設計にする
運用の現場では、ATTの許可率が低いことを理由にApple Search Adsの計測を諦めてしまう担当者がいますが、それはAdServicesの性質を取り違えています。ATTの許可率が仮に30%台であっても、AdServicesのpayloadからはキャンペーン・キーワード別の獲得が拒否ユーザー分も含めて読めるため、Apple Search Ads単体の運用改善には十分なデータが得られます。「ATT拒否＝計測ブラックボックス」という思い込みを外すことが、iOS計測の精度を一段引き上げる分岐点になります。この論点を運用者が判断できる形に翻訳できるかどうかが、代理店やパートナーの実力の差にもつながります。
実装でつまずくポイントと対処
AdServices Attribution APIの実装は、コード自体は短いものの、タイミングとエラーハンドリングで必ずと言っていいほど詰まります。ここでは実務で頻出するトラブルを症状ベースで整理します。公式リファレンスにも概念記事にも体系立てた記載がほとんどないため、この章が本記事の実務価値の中心です。症状を先に知っておくだけで、原因調査に費やす時間を大幅に短縮できます。
まず24時間TTLの問題です。attributionToken()で取得したトークンは発行から24時間で失効します。トークンを取得してから時間を置いてPOSTしようとすると、期限切れで弾かれます。対策はシンプルで、トークン取得とpayload取得を時間的に近づけ、取得したら速やかにAPIへ送ることです。サーバー側にトークンを退避して後でまとめて処理するバッチ設計にすると、この24時間に引っかかりやすいため、リアルタイムに近い処理フローが安全です。
次に初回nullとリトライの問題です。アプリ起動直後にトークンを取ろうとすると、まだトークンが生成されておらずnullが返ることがあります。また、トークンをPOSTしても、Apple側でアトリビューションデータがまだ生成されていない場合はHTTP 404が返り、データが揃うと200に変わります。この404は「エラー」ではなく「まだデータ未生成」を意味するため、一定間隔でリトライ（ポーリング）して200が返るのを待つ実装が必要です。数秒から数時間の遅延が起こり得るので、指数バックオフで数回リトライし、それでも取れなければ後続のバッチで再取得する二段構えにしておくと堅牢です。
| 症状 | 原因 | 対処 |
|---|---|---|
| トークンがnull | 起動直後で未生成・シミュレータ実行 | 実機で試す・少し待ってリトライ |
| POSTで期限切れ扱い | 24時間TTLを超過 | 取得後すぐ送信・退避しない |
| HTTP 404が返る | Apple側でデータ未生成 | 200になるまでポーリング |
| シミュレータで動かない | AdServicesは実機のみ対応 | 実機でのみ検証する |
| AAAttributionErrorが発生 | ネットワーク・権限・内部エラー | エラー型別に分岐して対処 |
シミュレータで動かないのも頻出です。AdServicesのトークン取得は実機でのみ機能し、シミュレータではトークンが取れません。開発中に「nullしか返らない」と悩む原因の多くはこれで、検証は必ず実機で行う必要があります。あわせて、attributionToken()はメインスレッドをブロックし得る同期的な処理になり得るため、バックグラウンドスレッドで呼ぶなどUIをブロックしない配慮も入れておくとユーザー体験を損ないません。
最後にAAAttributionErrorのハンドリングです。トークン取得時にはネットワークエラー、内部エラー、権限エラーなど複数のエラー型が返り得ます。すべてを同じ握りつぶし方で処理すると、リトライすべきケースと諦めるべきケースの区別がつかなくなります。ネットワーク起因なら再試行、内部エラーなら間隔を空けて再試行、といったエラー型別の分岐を入れておくと、取りこぼしを最小化できます。エラーを黙って無視せず、ログに残して後から歩留まりを検証できるようにしておくことも重要です。
MMPを使わず自社でpayloadを受けて計測する最小構成の設計
AdServices Attribution APIの大きな魅力は、AdjustやAppsFlyerといったMMP（モバイル計測パートナー）を噛ませなくても、Apple Search Adsの成果を自社だけで読める点にあります。既存記事の多くはMMP前提で書かれていますが、キャンペーン数が限られていたり、まずはApple Search Adsの成果だけを正確に押さえたいフェーズなら、自前で最小構成を組むほうがコストも透明性も有利になることがあります。ここでは、その最小構成の設計指針を示します。
最小構成の骨格は、「アプリでトークン取得→自社サーバーへ送信→サーバーがApple APIへPOST→返ったpayloadを自社DBに保存→レポートで集計」という一本道です。アプリ側はトークンを取ってサーバーに渡すだけに徹し、リトライやポーリング、24時間TTL対策、名称解決といった重い処理はサーバー側に寄せます。サーバー側に処理を集約することで、ログ保全・リトライ制御・データ保管が一元化でき、計測の取りこぼしを追跡しやすくなります。payloadに含まれるcampaignIdやkeywordIdは、Apple Search AdsのレポートAPIと突き合わせて名称に解決し、BIツールや管理画面で読める形に変換します。
この自前構成が向くのは、Apple Search Adsが主要チャネルで、他媒体を含めた横断計測の優先度がまだ高くない場合です。逆に、Meta・TikTok・Googleなど複数媒体を横断して純増効果まで測りたいなら、SKAdNetworkやAdAttributionKitを扱うMMPの導入が現実的になります。「AdServicesは自前、横断計測はMMP」というハイブリッド構成も十分あり得ます。どこまでを内製し、どこからを外部に委ねるかは、チャネル構成・工数・専門性のバランスで決めるべき経営判断です。
この判断は、広告運用そのものを内製するか外注するかという、より大きな意思決定と地続きです。計測基盤の内製・外注の線引きに迷う場合は、広告運用代行の費用構造や委託判断を整理した記事が判断材料になります。自社で握るべき部分と任せるべき部分の切り分けの考え方が参考になります。自社の体制に照らして最小構成をどう設計すべきか具体的に相談したい場合は、ハーマンドットへの無料相談で計測設計から一緒に整理できます。
実装後の運用フェーズでは、payloadから得たキーワード別の獲得効率をApple Search Adsの入札や除外設定にフィードバックし、獲得単価を継続的に改善していくサイクルが本番になります。計測は目的ではなく手段であり、読み取ったデータを配信改善に還元して初めて投資対効果が生まれます。この一連の設計・実装・運用改善までを社内リソースだけで回すのが難しい場合、計測に強い運用パートナーと組むことで立ち上げを短縮できます。広告運用の外注可否や委託先の見極め方は、次の記事で判断軸を詳しく整理しています。
まとめはAdServices payloadを正しく読むための要点
AdServices Attribution APIは、Apple Search Adsの成果を決定論的に、しかもMMPを介さず自社だけでも読める希少な仕組みです。ただし正しく使うには、トークン取得からpayload復号までの流れ、フィールドの意味、standardとdetailedの差分、ATTとの関係、そして実装の落とし穴を体系的に理解しておく必要があります。断片的な英語情報や運用視点の概念解説だけでは、本番で必ずどこかで詰まります。実装の途中で判断に迷ったら、計測設計に強い運用パートナーへ相談することで立ち上げの時間を大きく短縮できます。最後に、実装者と運用者の双方が押さえるべき要点を整理します。
- attributionフラグで最初に分岐する。ASA経由かどうかを見ずにcampaignIdを読むとオーガニックを誤計上する。conversionTypeで新規と再DLも区別する。
- standardで取れるIDを主軸に、detailedのclickDateは補助扱い。clickDateを必須条件にすると本番で計測が止まる。分単位丸めも前提にする。
- ATT拒否でも基本のアトリビューションは取れる。「ATT拒否＝計測不能」は誤解。24時間TTL・初回null・404ポーリング・実機必須の落とし穴を押さえれば自前計測は成立する。
まずは無料で広告アカウント診断を
iOSのアトリビューションは、AdServicesのpayload解釈だけでなく、SKAdNetworkやAdAttributionKitとの役割分担、ATTを踏まえたKPI設計まで含めて設計しないと、数字の乖離や取りこぼしが起こります。自社で実装を進めているものの「このpayloadの読み方で合っているか」「Apple Search Adsの成果を配信改善にどう還元すべきか」に不安がある場合は、計測設計と運用改善の両輪で伴走できるパートナーに一度見てもらうのが近道です。
株式会社ハーマンドットでは、Apple Search Adsを含むiOS計測の設計から、キーワード別の獲得効率を配信改善へつなぐ運用まで、実装と運用の両面でご支援しています。まずは現状のアカウントとデータ計測を客観的に診断し、どこに改善余地があるかを具体的にお伝えします。
初回相談は完全無料・所要時間30分・オンライン対応可能です。