People-Based Attribution(PBA)は、AppsFlyerの進化したWeb計測ソリューションであるWeb Performance Measurementに置き換わります。この記事では、変更点、移行手順、レポートとサーバー側の連携に関する全フィールドの対応関係を説明します。
Web計測をアップグレードする理由
Web計測の重要性は、これまで以上に高まっています。 Webサイトは、多くのユーザーがコンバージョンに至る場所であり、モバイルアプリへと向かう経路の出発点でもあります。単なるランディングページではなく、診断コンテンツ、ユーザーに合わせたオンボーディング、ペイウォール、Webストアなどを通じてユーザーを獲得する一連のファネルとして機能し、利用意向の高いユーザーをより低いコストで獲得できることも少なくありません。
AppsFlyerは、Web計測をモバイル計測と同じ水準に引き上げます。従来のWeb製品であるPeople-Based Attribution(PBA)は、AppsFlyerの中核となるアトリビューションエンジンと統一データモデルを基盤にしたWeb Performance Measurementに置き換わります。 Web Performance Measurementは、現在のPBAの機能をすべて備え、さらに以下を提供します。
- 信頼できるデータの一元化:Webとモバイルアプリの計測を1か所にまとめ、コスト集計、最適化ポストバック、クリエイティブ最適化を組み合わせて利用できます。
- 予算配分の判断を改善:ビジネスのロジックに合った柔軟なアトリビューションにより、実際に成果を上げているキャンペーンへの投資を強化できます。
- ROASの向上:アドネットワークへの最適化ポストバックを充実させるとともに、すべてをサーバー側で実装してより多くのコンバージョンを計測できます。これにより、アドネットワークはより質の高いシグナルに基づいて最適化できます。
- クロスプラットフォームのROIを正確に把握:Web、アプリ、その他あらゆるプラットフォームをまたぐユーザージャーニーを計測できます。
- シンプルで統一されたレポート:すべてのプラットフォームで1つのダッシュボードと共通のデータレポートを使用でき、データは毎時更新されます。
Web SDKを入れ替える必要はありません。 Web Performance Measurementは同じSDKを使用するため、Webサイトのコード変更は不要です。それ以外の切り替え作業は、現在データをダッシュボード、Data Locker、サーバー間(S2S)APIのどれで取得しているかによって異なります。
PBAとWeb Performance Measurementの比較
このセクションでは、機能全般と流入元の判定の2つの観点で、PBAとWeb Performance Measurementを比較します。
Web Performance MeasurementとPBAの比較
以下の表は、データ、レポート、アトリビューションに関するPBAとWeb Performance Measurementの機能を比較したものです。
| 機能 | 説明 | PBA | Web Performance Measurement |
| データ | |||
| データの更新頻度 | レポートでデータを利用できるまでの時間 | ✗ 日次 | ✓ 毎時のレポート。データの反映まで約2時間 |
| データモデル | モバイルアトリビューションデータとのスキーマの整合性 | ✗ モバイルとは異なる | ✓ モバイルと共通で、結合や分析が容易 |
| レポート | |||
| アクティビティダッシュボード | イベントの発生時刻を基準とするダッシュボード | ✓ 対応 | ✓ 対応 |
| コホートダッシュボード | 獲得コホート別に、時間の経過に伴う成果を分析 | ✗ 非対応 | ✓ 対応 |
| Data Lockerのローデータ | Data Lockerから出力したアトリビューションのローデータを利用 | ✓ 対応 | ✓ 対応 |
| 広告レベルの詳細度 | キャンペーンから広告レベルまでのレポートの内訳 | ✗ ダッシュボードのみ。ローデータには含まれない | ✓ ダッシュボードとローデータの両方で、キャンペーンの詳細な内訳を提供 |
| クロスプラットフォームのLTV | Webとモバイルのユーザージャーニーを紐付け、LTVを一元的に把握 | ✗ 非対応 | ✓ 対応 |
| コストとシグナル | |||
| Web広告のコスト | Webキャンペーンの広告費を取り込み、レポートに表示 | ✗ 非対応 | ✓ 対応 |
| 最適化ポストバック | 最適化用のシグナルをアドネットワークに送信 | ✗ 非対応 | ✓ 対応 |
| 実装 | |||
| Web SDK(ピクセル) | Webへの訪問とイベントを計測するクライアント側SDK | ✓ 対応 | ✓ 同じSDKを使用。コード変更は不要 |
| S2Sへの対応 | 訪問とイベントをすべてサーバー側で計測 | ✗ イベントのみ | ✓ イベントと訪問。すべてをサーバー側で実装可能。 |
| アトリビューションエンジン | |||
| アトリビューションに関する期間設定 | ルックバック期間、アトリビューション期間、リエンゲージメント期間、休眠期間を設定可能 | ✗ クリックルックバック期間のみ | ✓ 5種類の期間を設定可能(すべて制御可能) |
| カスタムUAイベント | 初回訪問以外に、ユーザー獲得(UA)として扱うイベントを定義 | ✗ 初回訪問のみ | ✓ 任意のカスタムイベント(新規登録、購入など) |
| UAとリターゲティング | 新規獲得とリエンゲージメントを分けて計上 | ✗ UAの概念はなく、イベントをラストタッチにアトリビューション | ✓ UAとリターゲティングの専用ビューを備え、二重アトリビューションによりそれぞれに計上 |
流入元の判定 | PBAとWeb Performance Measurementの比較
メディアソース、チャネル、キャンペーンの値がPBAのレポートと異なる場合は、以下の変更が理由です。両者の基本的な仕組みは同じです。Web訪問時のURLパラメータとリファラを優先順位に従って確認し、最初に一致したルールに基づいてメディアソースを判定します。ただし、一部のルールが変わったため、レポートに表示される値も変わります。詳細は、PBAのメディアソースアトリビューションルールと「流入元の判定について」を参照してください。
メディアソースの値の変更
| 判定条件 | PBAの値 | 新しい値 |
| Googleのディスプレイ・動画広告(utm_source=Google + utm_medium= cpm / display/banner/video/listing) | doubleclick_int |
dv360_int |
| UTM経由のTwitter(twitter + cpc) | X Ads |
Web Performance Measurementでは、表示名に変換されるPIDの種類も増えています。たとえば、iossearchads_intはApple Search Ads、metweb_intはFacebook Ads、twitterweb_intはTwitter、tiktokweb_intはtiktokglobal_int、snapweb_intはsnapchat_intに変換されます。従来の生の値を前提に作成したレポートは、新しい値に対応させる必要があります。
対象クリックIDの拡大とdclidの除外
PBAでは、3つのクリックIDを判定に使用していました。gclidはgoogleadwords_int、dclidはdoubleclick_int、msclkidはbingsearch_intに対応していました。
Web Performance Measurementでは、より多くのIDを判定に使用します。gclid/wbraid/gbraidはgoogleadwords_int、msclkidはbingsearch_int、twclidはTwitter、vmcidはyahoogemini_int、sccidはsnapchat_int、li_fat_idはlinkedin_int、ttclidはtiktokglobal_int、tbclidはtaboola_int、ob_click_id/dicboはoutbrain_int、yclidはyandex_int、rdt_cidはreddit_intに対応します。
動作上の変更は2点です。dclidは単独では判定に使用されなくなり(PBAではdoubleclick_intと判定)、fbclidは明示的に判定対象外となっています。
UTMカスタムルールの拡大
Web Performance Measurementでは、utm_sourceとutm_mediumを組み合わせたカスタムマッピングが拡充されています。PBAでは個別の限られたmedium値にのみ対応していましたが、新方式ではpaid、paid_search、paid-searchなどの類似表現に加え、TikTok、Snapchat、Pinterestにも対応しています。一致するカスタムルールがない場合は、どちらもutm_sourceの生の値を使用します。
チャネル
チャネルの値の形式も変わります。PBAのDirect / Organic search / Social media / Email / Ad / Referral / Otherは、新方式ではDIRECT / ORGANIC_SEARCH / SOCIAL_MEDIA / EMAIL / AD / REFERRAL / OTHERになります。従来のラベルを使用するフィルターやグループ化は更新が必要です。
Web Performance Measurementへの移行
すべてのユーザーに必須の移行手順が1つあります。その後、ご利用のPBAの構成に該当する手順を行ってください。
数値に差が生じることの確認(全ユーザー)
PBAの数値は、移行後の数値と完全には一致しません。 Web Performance Measurementのアトリビューションロジックは、より高度で柔軟です。 PBAは独自のメディアソースアトリビューションルールを使用していましたが、Web Performance Measurementでは、流入元の判定が改善されています。想定される値については、後述の「流入元の判定 | PBAとWeb Performance Measurementの比較」を参照してください。セッションの記録ロジック自体は変わりません。引き続き、業界で一般的な30分のアクティビティを1つのセッションとして扱います。
ステップ1. Webアプリの作成(全ユーザーに必須)
- 新しいWebアプリを作成し、[Web SDK ID]で既存のWeb Dev Keyを選択します。これにより、Webサイトのコードを変更せず、そのまま使用できます。
- 新しいアプリでアトリビューションを設定します。
ステップ2. S2S APIでイベントを送信している場合
新しいS2S APIに移行します。
- PBA Web-S2Sから新しいS2S APIへの移行を参照し、現在のPBA S2S実装との違い、エンドポイント、認証、ペイロードのフィールドを確認します。
- Web Performance Measurement用の新しいS2S APIを設定します。
- サーバー側の連携を更新し、新しいエンドポイントに送信するようにします。
ステップ3. PBAのローデータレポートを利用している場合
新しいData Lockerレポートに切り替えます。ユーザーイベントレポートが、PBAのWebサイト訪問レポートとWebサイトイベントレポートに代わるレポートになります。
- Data Lockerを利用できることを確認します。利用できない場合は、アカウントへの追加または購入が必要です。
- ローデータのフィールド対応表で、全フィールドの対応関係と、名前や定義が変わるフィールド、廃止されるフィールドを確認します。
- Data LockerからのAppsFlyer Web Attributionレポートデータの出力に従って、新しいレポートを有効にします。
- BI・ETLの参照先を、新しいレポートの場所とフィールドに変更します。この手順は、SDK経由とS2S経由のどちらでイベントを受信する場合にも必要です。両方とも同じローデータレポートに記録されます。
ステップ4. クロスプラットフォームレポートにPBAのブランドバンドルを使用している場合
- プロダクトラインを作成します。
- そのプロダクトラインにWebアプリと他のアプリをまとめると、クロスプラットフォームのユーザーLTVレポートを利用できます。
提供を終了する機能
| 機能 | 変更点 | 詳細 |
| コンバージョン経路 | すでに廃止済みです。 | N/A |
| Webアシストインストール(後のモバイルインストールに貢献したWebキャンペーンへの計上) | 専用の「Webアシストインストール」ビューはありません。 |
Webからアプリへのジャーニーは、Smart ScriptとSmart Bannerで計測します。クロスプラットフォームレポートでは、完全に同じではありませんが、類似の分析が可能です。 PBAと同様に、カスタマーユーザーID(CUID)を基準とします。
|
| 過去に遡る再計算 | デフォルトの30分の遅延時間を超えて、過去に遡る再計算は行いません。 | アトリビューションは30分の遅延後に確定します。この間にユーザーの識別情報を取得できるようにするためです。 |
| ローデータのフィールド | モバイル関連のフィールドは、Webでは廃止されます。一部のフィールドは名前が変わり、一部の値も変わります。 | 全フィールドの対応関係は、ローデータのフィールド対応表を参照してください。 |
| 遅れて届くS2Sイベント | イベントが発生したUTC日の終了から30分を過ぎて届いたイベントも受け付けられますが、イベントの発生時刻はAppsFlyerの受信時刻に置き換えられます。 | イベントは1日分をまとめてアップロードせず、リアルタイムに、できれば発生から30分以内に送信してください。正確なアトリビューションには、イベントの発生に近いタイミングでの受信が必要です。この処理は、既存のモバイルの動作と共通です。 |
ローデータのフィールド対応表
すでにPBAのWebサイト訪問・Webサイトイベントのローデータレポートを利用している場合は、以下の変更があります。レポートの提供先はData Lockerに変わります。以下は、PBAのローデータレポートを基準に、新しいユーザーイベントレポートとの対応関係をフィールドごとにまとめたものです。
各プラットフォームのローデータとクロスプラットフォームレポートは、Data Lockerでのみ利用できます。 Data Lockerをまだ利用できない場合は、上記のステップ3または4を参照してください。
- 変更なし:フィールド名もデータも同じです。
- 名称変更:データは同じで、列名が変わります。
- 定義変更:名前は同じか似ていますが、データまたは値の形式が変わります(再利用には注意が必要です)。
- 廃止:新しいレポートに対応するフィールドはありません。
| フィールド名 | 説明 | ステータス | 新しいフィールド・補足 |
advertising_id |
広告ID(GAID) | 廃止 | PBAでクロスプラットフォームの紐付けに使用していた、モバイル・デバイスの広告IDです。クロスプラットフォームのLTVとユーザージャーニーのレポートはCUIDを基準とし、このフィールドは使用しません。 |
af_web_id |
Web SDKから送信されるCookie ID | 名称変更 |
appsflyer_id_value。同じWeb Cookieです。 |
amazon_aid |
Amazon Fire TVの広告ID | 廃止 | モバイル・デバイスのIDで、Webには関係しません。 |
android_id |
AndroidデバイスID | 廃止 | モバイル・デバイスのIDで、Webには関係しません。 |
app_id |
直近にインストールされたアプリのID | 廃止 | モバイルのクロスプラットフォーム用フィールドです。新しいレポートのWebアプリ識別子はunified_app_id("website-{domain}")であり、別の概念です。 |
app_name |
直近のアプリ名 | 変更なし |
app_name. |
app_version |
直近のアプリバージョン | 廃止 | モバイルのクロスプラットフォーム用フィールドで、Webには関係しません。 |
appsflyer_id |
AppsFlyer(インストール)ID | 廃止 | モバイルのインストールIDです。新しいappsflyer_id_valueはWeb Cookie(af_web_id)であり、別の識別子です。 |
attributed_touch_time |
アトリビューション先となったWeb訪問のタイムスタンプ | 名称変更 |
event_time__attribution。アトリビューション先のタッチ(エンゲージメント)の時刻です。 |
attributed_touch_type |
タッチポイントの種類。常に"web visit" | 廃止 | PBAでは定数でした。訪問かイベントかの区分は、end_user_event_type(SESSION / IN_APP)で示されます。 |
bundle_id |
PBAのバンドルID | 廃止 | クロスプラットフォームレポートのプロダクトラインによるグループ化(Webアプリとモバイルアプリ)に置き換わります。 |
campaign |
Webサイト訪問のアトリビューション先 | 名称変更 |
campaign_name. |
campaign_id |
Webサイト訪問のアトリビューション先 | 変更なし |
campaign_id. |
city |
IPアドレスを使って判定 | 変更なし |
city. |
country_code |
IPアドレスを使って判定 | 変更なし |
country_code. |
customer_user_id |
カスタマーユーザーID(CUID) | 変更なし |
customer_user_id. |
device_type |
デバイスの種類 | 名称変更 |
device_category。値が異なります("Desktop"に対し、"MOBILE_PHONE" / "TV"など)。 |
dma |
IPアドレスを使って判定 | 変更なし |
dma. |
event_name |
訪問:常に"website visit"。イベント:送信されたイベント名 | 定義変更 | 訪問では空欄になります(PBAでは"website visit")。イベントでは変更ありません。 |
event_revenue |
購入時の通貨で表したイベントの収益額 | 名称変更 |
revenue_value_original. |
event_revenue_currency |
event_revenueの3桁の通貨コード
|
名称変更 |
revenue_currency_original. |
event_revenue_usd |
event_revenueをUSDに換算した値 |
名称変更 |
revenue_usd. |
event_source |
Web SDKまたはサーバー間通信 | 変更なし |
event_source. |
event_time |
訪問:訪問の時刻。イベント:イベントの発生時刻 | 変更なし |
event_time. |
event_type |
標準イベント / コンバージョンイベント / Webサイト訪問 | 定義変更 | コンバージョンイベントを示す区分は廃止されます。訪問かイベントかの区分は、end_user_event_type(SESSION / IN_APP)で示されます。 |
event_url |
イベントが発生したWebページのURL(訪問の場合はOriginal URLと同じ) | 変更なし |
event_url。URLのクエリパラメータ(UTMなど)の主な参照先にもなります。 |
event_value |
イベント:JSON形式のイベント詳細。訪問:null | 変更なし |
event_value. |
idfa |
広告識別子 | 廃止 | モバイル・デバイスのIDで、Webには関係しません。 |
idfv |
広告識別子 | 廃止 | モバイル・デバイスのIDで、Webには関係しません。 |
imei |
デバイス識別子 | 廃止 | モバイル・デバイスのIDで、Webには関係しません。 |
install_time |
直近のアプリのインストール時刻 | 廃止 | モバイルのクロスプラットフォーム用フィールドです。 Webのユーザー獲得(コンバージョン)時刻はevent_time__conversionであり、別の概念です。 |
ip |
訪問者のIPアドレス | 名称変更 |
ip_address_value。値は同じで、ハッシュ化の方式を示すip_address_typeが追加されます。 |
language |
ユーザーエージェントが送信する値(例:"English") | 定義変更 |
language。値の形式がISO 639-1と国コードに変わります。 |
media_channel |
Webサイト訪問のアトリビューション先("Ad") | 廃止 | 必要に応じてsub_param_1-5で対応できます。 |
media_source |
Webサイト訪問のアトリビューション先 | 変更なし |
media_source. |
media_type |
Webサイト訪問のアトリビューション先("Paid") | 廃止 | Webでは空欄です。オーガニックか有料かの区分は、真偽値のis_organicで示されます。 |
oaid |
広告識別子 | 廃止 | モバイル・デバイスのIDで、Webには関係しません。 |
original_url |
アトリビューション先の訪問でユーザーをリダイレクトしたURL | 名称変更 |
event_urlに統合されます(訪問の場合、event_urlは元のURLと同じです)。単独の列はなくなります。 |
platform |
プラットフォーム("macOS"、"Windows") | 定義変更 | プラットフォームは常に"WEBSITE"です。 OSはos_version / user_agentに移ります。 |
postal_code |
IPアドレスを使って判定 | 変更なし |
postal_code. |
query_params |
JSON形式のリダイレクト元URLのクエリパラメータ | 廃止 | 生のクエリ文字列はevent_urlに含まれます。解析済みJSONの列はなくなります。 |
referrer |
アトリビューション先のWebサイト訪問のHTTPリファラ | 名称変更 |
http_referrer. |
region |
IPアドレスを使って判定("NA") | 名称変更 |
continent。大陸コードです(例:"NA")。 |
state |
IPアドレスを使って判定 | 変更なし |
state. |
Data LockerのETL移行に使えるコーディングエージェント用プロンプト
移行を円滑に進めるため、AIコーディングエージェント(Claude Code、Cursorなど)ですぐに使えるプロンプトを用意しました。エージェントが既存のETLコードにアクセスできるようにし、以下のプロンプトを貼り付けてください。全フィールドの対応関係と、動作上のすべての違いが含まれています。エージェントはこのプロンプトに従って現在のパイプラインを把握し、新しいレポートに対応するよう再構築します。
AppsFlyerの従来のPBA Data Lockerローデータレポート(Webサイト訪問とWebサイトイベント)を利用するETLパイプラインを、Web Performance MeasurementのData Lockerレポート(ユーザーイベント)に移行してください。構造上の変更、全フィールドの対応関係、検証手順など、必要な情報はすべてこのプロンプトに記載されています。ここに書かれていないことを推測しないでください。不明確な点があれば私に確認してください。
## ステップ1:現在のパイプラインの把握
コードを書く前に、既存のコードベースを調べ、以下を一覧にしてください。
1. 利用しているPBAレポート(Webサイト訪問、Webサイトイベント、またはその両方)と、その取り込み先。
2. 読み取っているすべてのPBAフィールドと、各フィールドの後続処理での用途(変換、結合、ダッシュボード、アラート、出力)。
3. 読み込みの頻度とスケジュールの前提(PBAは日次で配信)。
4. 訪問の行とイベントの行を分離または結合する処理。
5. PBAフィールドの値に依存するフィルター、グループ化、ハードコードされた値(media_source名、チャネルラベル、event_type、platformの値など)。
一覧を提示し、私の確認を得てから次に進んでください。
## ステップ2:以下の質問を私に確認
1. 新しいユーザーイベントレポートは、Data Lockerで有効になっていますか(AppsFlyerのUIで有効化)?まだの場合は、先に私が有効にする必要があります。
2. 新しいWebアプリの統合アプリIDは何ですか?形式:"website-{domain}"(例:website-www.example.com)。不明な場合は、作業を続ける前にAppsFlyerのダッシュボードで確認します。
3. 新旧のパイプラインを並行稼働させて出力を比較する期間を設けますか。それとも、直接切り替えますか?並行稼働を推奨してください。
4. 新しいパイプラインでは、コンバージョンレポート(アトリビューションごとに一意の行を持ち、重複行なし)や、クロスプラットフォームのユーザーイベントレポート(CUIDで重複排除した、Webとモバイルのユーザーレベルデータ)も取り込みますか?デフォルトの対象は、PBAレポートの直接の後継となる、プラットフォーム単位のユーザーイベントレポートです。
## 設計で考慮する構造上の変更
1. **2つのレポートを1つに統合。** PBAでは、訪問とイベントが別々のレポートでした。新しいユーザーイベントレポートには両方が含まれます。訪問はend_user_event_type = 'SESSION'の行、イベントはend_user_event_type = 'IN_APP'の行です。有効なevent_nameが入るのはIN_APPの行のみです。SESSIONの行ではevent_nameは空欄です(PBAでは"website visit"が入っていました)。
2. **すべてのプラットフォームで共通のスキーマ。** Webサイト、モバイル、CTV、PCが同じレポートを使用します。 Webデータを抽出するには、必ずplatform = 'WEBSITE'で絞り込んでください。
3. **二重アトリビューションの重複を排除。** 同じ操作が、メインの計上先の行とサブの計上先の行(UAビューのLTVに使用する元のUAソース)の2行に表示される場合があります。二重計上を避けるため、デフォルトではis_primary_attribution = trueで絞り込んでください。このフィルターを外すのは、conversion_typeを使ってUAビューとリターゲティングビューを個別に分析する場合だけにしてください。
4. **日次から毎時に変更。** 新しいレポートは毎時配信され、データの反映まで約2時間かかります。 1日1回の配信ではなく、1時間ごとのバッチを前提に差分読み込みを再設計してください。
5. **オーガニックと有料の区分。** PBAのmedia_type("Paid")は廃止されます。真偽値のis_organicを使用し、media_sourceからオーガニックか有料かを推測しないでください。
6. **ユーザーの集計。** COALESCE(customer_user_id, appsflyer_id_value)を使って、ユーザーを集計・結合してください。安定したカスタマーユーザーIDを優先し、ない場合はCookieベースのIDを使います。
7. **空の値。** STRINGフィールドは''、NUMERICフィールドはNULLです。
## フィールド別の対応関係(PBA → ユーザーイベント)
ステータスの凡例:変更なし=名前もデータも同じ。名称変更=データは同じで、新しい列名に変更。定義変更=データまたは値の形式が変更(取り扱いに注意)。廃止=対応するフィールドなし。
| PBAのフィールド | ステータス | 新しいフィールド・対応方法 |
|---|---|---|
| advertising_id | 廃止 | モバイル・デバイスID。クロスプラットフォームレポートはCUIDを基準とするため、削除してください。 |
| af_web_id | 名称変更 | appsflyer_id_value。同じWeb Cookieです。 |
| amazon_aid | 廃止 | モバイル・デバイスIDで、Webには関係しません。 |
| android_id | 廃止 | モバイル・デバイスIDで、Webには関係しません。 |
| app_id | 廃止 | モバイルのクロスプラットフォーム用フィールドです。新しいWebアプリ識別子はunified_app_id("website-{domain}")であり、名称変更ではなく別の概念です。 |
| app_name | 変更なし | app_name。 |
| app_version | 廃止 | モバイルのクロスプラットフォーム用フィールドです。 |
| appsflyer_id | 廃止 | モバイルのインストールIDです。注意:新しいappsflyer_id_valueはWeb Cookie(PBAのaf_web_id)であり、このフィールドとは異なります。 |
| attributed_touch_time | 名称変更 | event_time__attribution。 |
| attributed_touch_type | 廃止 | 定数でした。訪問かイベントかの区分は、end_user_event_typeで示されます。 |
| bundle_id | 廃止 | クロスプラットフォームレポートのプロダクトラインによるグループ化に置き換わります。 |
| campaign | 名称変更 | campaign_name。 |
| campaign_id | 変更なし | campaign_id。 |
| city | 変更なし | city。 |
| country_code | 変更なし | country_code。 |
| customer_user_id | 変更なし | customer_user_id。 |
| device_type | 名称変更と値の変更 | device_category。値が異なります(例:"Desktop" → "MOBILE_PHONE" / "TV"の形式)。値に依存する処理を更新してください。 |
| dma | 変更なし | dma。 |
| event_name | 定義変更 | イベント:変更なし。訪問:空欄に変更(PBAでは"website visit")。訪問の特定にはend_user_event_type = 'SESSION'を使用してください。 |
| event_revenue | 名称変更 | revenue_value_original。 |
| event_revenue_currency | 名称変更 | revenue_currency_original。 |
| event_revenue_usd | 名称変更 | revenue_usd。 |
| event_source | 変更なし | event_source。 |
| event_time | 変更なし | event_time。 |
| event_type | 定義変更 | "Conversion event"の区分は廃止されます。訪問かイベントかの区分は、end_user_event_type(SESSION / IN_APP)で示されます。 |
| event_url | 変更なし | event_url。URLのクエリパラメータ(UTMなど)の主な参照先にもなります。 |
| event_value | 変更なし | event_value。 |
| idfa / idfv / imei / oaid | 廃止 | モバイル・デバイスIDで、Webには関係しません。 |
| install_time | 廃止 | モバイル用フィールドです。 Webのユーザー獲得時刻はevent_time__conversionであり、別の概念です。 |
| ip | 名称変更 | ip_address_value(ハッシュ化の方式を示すip_address_typeを追加)。 |
| language | 定義変更 | language。形式がISO 639-1と国コードに変わります(従来は"English"など)。 |
| media_channel | 廃止 | 必要に応じてsub_param_1-5で対応できます。 |
| media_source | 変更なし | media_source(ただし、後述する値の変更を参照)。 |
| media_type | 廃止 | 代わりに真偽値のis_organicを使用してください。 |
| original_url | 名称変更 | event_urlに統合(訪問の場合、event_urlは元のURLと同じ)。単独の列はなくなります。 |
| platform | 定義変更 | platformは常に"WEBSITE"です。 OSはos_version / user_agentに移ります。 |
| postal_code | 変更なし | postal_code。 |
| query_params | 廃止 | 生のクエリ文字列はevent_urlに含まれ、解析済みJSONの列はなくなります。必要に応じて、event_urlからの解析を再実装してください。 |
| referrer | 名称変更 | http_referrer。 |
| region | 名称変更 | continent。大陸コードです(例:"NA")。 |
| state | 変更なし | state。 |
## アトリビューション関連の値の変更(フィルターとグループ化を更新)
アトリビューションエンジンの流入元の判定方法が異なるため、フィールド名が同じでも一部の値が変わります。
- media_sourceの値の変更:doubleclick_int → dv360_int(UTM経由のGoogleのディスプレイ・動画広告)、"X Ads" → "Twitter"(UTM経由のTwitter)。表示名に変換されるPIDも増えています(例:iossearchads_int → Apple Search Ads、metweb_int → Facebook Ads、tiktokweb_int → tiktokglobal_int、snapweb_int → snapchat_int)。
- チャネルラベルの形式変更:Direct / Organic search / Social media / Email / Ad / Referral / Otherが、DIRECT / ORGANIC_SEARCH / SOCIAL_MEDIA / EMAIL / AD / REFERRAL / OTHERになります。
- 対象クリックIDの拡大(より多くのネットワークをクリックIDから判定)。dclidは単独では判定に使用されず、fbclidも使用されません。
コードベースを調べ、これらの従来の値に依存するフィルター、CASE、結合キー、ダッシュボードのグループ化を更新してください。
## ステップ3:構築
1. 新しいETLの設計(取り込み、スキーマ、毎時の差分処理、「構造上の変更」で示した必須のフィルター)を提案してください。
2. 私の承認後、既存の規約とインフラを活用して実装してください。
3. 一覧にある廃止フィールドのうち後続処理で使用中のものはすべて、利用先と対応案(削除、提示された代替への置き換え、業務担当者への確認)を示してください。
## ステップ4:検証
1. 同じ日付範囲で両方のパイプラインを実行し、訪問(SESSION行)とPBAのWebサイト訪問、イベント(IN_APP行)とPBAのWebサイトイベント、および収益の合計を比較してください。
2. 数値の一致ではなく、差が生じることを前提にしてください。新しいアトリビューションロジックはより高度なため、アトリビューションの分析軸(media_source、campaign)はPBAと完全には一致しません。セッションの集計ロジックは変わらないため(30分のアクティビティ)、訪問数はおおむね同程度になる想定です。
3. is_primary_attributionのフィルターがすべての箇所で適用されていることを確認してください。ない場合、イベント数が過大になります。
4. 簡潔な移行レポートを作成してください。マッピングした項目、削除した項目、値の変更点、業務担当者による確認が必要な未解決事項を含めます。
PBA Web-S2Sから新しいS2S APIへの移行
Web Server-to-server events API(Web-S2S)でPBAにイベントを送信している場合は、新しいS2S APIに移行してください。新しいAPIは訪問とイベントの両方に対応しているため、Webサイトの計測をすべてサーバー側で実行できます。PBAのS2Sはイベントのみを受け付けます。
エンドポイントと認証
| PBA Web-S2S | 新しいS2S API | |
| ベースURL | https://webs2s.appsflyer.com |
https://events.appsflyer.com |
| イベントの呼び出し | POST /v1/{bundleId}/event |
POST /v2.0/s2s/inapps/app/web/{appId} |
| 訪問の呼び出し | 非対応(訪問はWeb SDK経由のみ) | POST /v2.0/s2s/visits/app/web/{appId} |
| 識別子の関連付けの呼び出し |
POST /v1/{bundleId}/setcuid(CUIDとWebユーザーを関連付ける個別の呼び出し) |
なし。各イベント・訪問のuser_idオブジェクト内に識別子を含めて送信 |
| アプリ識別子 |
パス内のbundleId(ブランドバンドルID) |
パス内のappId=Webのunified_app_id("website-{domain}") |
| 認証 |
毎回の呼び出しのJSON本文内にwebDevKeyを設定 |
S2S APIキーを含むAuthorizationヘッダー |
| コンテンツタイプ | application/json |
application/json |
| 成功時のレスポンス | 200 OK | 202 Accepted |
ペイロードのフィールド対応表
| PBA Web-S2Sのフィールド | 新しいS2Sのフィールド | 注意 |
customerUserId |
user_id.customer_user_id |
user_idオブジェクト内にネストされます。 |
afUserId |
user_id.appsflyer_id |
user_idオブジェクト内にネストされます。 customer_user_idかappsflyer_idの少なくとも一方を送信し、ユーザーを識別できた場合は両方を送信してください。 |
webDevKey |
N/A | 本文から削除されます。認証はAuthorizationヘッダーに移り、アプリはパス内のappIdで識別されます。 |
eventType(常にEVENT) |
N/A | 削除されます。エンドポイント(/inappsか/visitsか)によって種類が決まります。 |
eventName |
event_name |
1〜64文字。@ = + -は使用できません。 |
timestamp(Unixミリ秒、13桁) |
timestamp(Unixミリ秒) |
形式は同じです。すべての呼び出しでの設定を推奨します。省略した場合は、AppsFlyerが受信時刻を使用します。 |
eventValue |
event_value |
自由形式で、custom_parametersサブオブジェクトに対応します。 |
eventRevenue |
event_revenue |
任意になりました(PBAではダッシュボード表示に必須)。 |
eventRevenueCurrency |
event_revenue_currency |
任意になりました(PBAではダッシュボード表示に必須)。 |
referrer |
http_referrer |
名称が変わります。 |
userAgent |
user_agent |
名称が変わります。 |
ip |
ip |
変更ありません。 |
| N/A | event_url |
新規追加。訪問では必須、イベントでは任意です。 |
| N/A | customer_dedup_id |
新規追加。別のソース(Web SDKなど)から届く同じイベントとの重複を排除します。 |
| N/A |
email_hashed, phone_number_hashed, phone_number_e164_hashed, first_name_hashed, last_name_hashed
|
新規追加。識別子情報を補完するため、正規化した値をSHA256でハッシュ化したもの(64文字の小文字16進数)。 |
S2S APIに関する注意
- 訪問をサーバー側で送信可能。 PBAのS2Sはイベントのみを受け付け、訪問はWeb SDKから送信する必要がありました。新しい/visitsエンドポイントでは、Webサイトの計測をすべてサーバー側で実装できます。
- setcuidの呼び出しが不要。 PBAはWeb SDKが必須だったため、CUIDをWebユーザーに紐付ける個別の呼び出しが必要でした。新しいAPIでは、すべてのリクエスト内に識別子を含めて送信するため、この手順は不要です。
- 遅延データの受付期間。イベントと訪問は1日分をまとめてアップロードせず、リアルタイムに、できればイベント発生から30分以内に送信してください。イベントが発生したUTC日の終了から30分を過ぎて届いたデータも受け付けられますが、イベントの発生時刻はAppsFlyerの受信時刻に置き換えられます。
S2Sサービスの移行に使えるコーディングエージェント用プロンプト
PBAのサーバー間APIでイベントを送信している場合に備え、AIコーディングエージェント(Claude Code、Cursorなど)ですぐに使えるプロンプトを用意しました。エージェントがAppsFlyerにイベントを送信するサービスにアクセスできるようにし、以下のプロンプトを貼り付けてください。エンドポイントとペイロードの全項目の対応関係が含まれています。エージェントはこのプロンプトに従って現在の実装を把握し、新しい実装を構築します。
AppsFlyerの従来のPBA Web S2SイベントAPI(webs2s.appsflyer.com)とのサーバー側連携を、Web Performance Measurement用の新しいS2S API(events.appsflyer.com)に移行してください。エンドポイント、認証、ペイロードの全項目の対応関係、動作の変更点など、必要な情報はすべてこのプロンプトに記載されています。ここに書かれていないことを推測しないでください。不明確な点があれば私に確認してください。
## ステップ0:コードを変更する前に以下を私に確認
1. 既存のサービスを直接変更しますか。それとも、新しいサービスやモジュールを並行して作成しますか(並行稼働と円滑な切り替えが可能)?既存のものと並行して新しいモジュールを作成する方法を推奨してください。
2. 新しいWebアプリの統合アプリIDはわかっていますか?形式:"website-{domain}"(例:website-www.example.com)。 URLパス内のPBAのバンドルIDに代わるものです。不明な場合は、作業を続ける前にAppsFlyerのダッシュボードで確認します。
3. 新しいS2S APIキーを取得していますか?認証は、リクエスト本文のwebDevKeyから、このキーを含むAuthorizationヘッダーに移ります。まだの場合は、AppsFlyerのダッシュボードから取得します。
4. PBAと同様にイベントのみを送信しますか。それとも、新しい訪問エンドポイントも使用しますか?新しいAPIはサーバー側からの訪問送信に対応し、Webサイトの計測をすべてサーバー側で実行できます。PBAはイベントのみを受け付けていました。
5. サイトでAppsFlyer Web SDKを引き続き使用していますか?(訪問をSDKから送信するか、SDKとS2S間のイベントの重複排除が必要かを判断するためです。)
## ステップ1:現在のサービスの把握
コードベースを調べ、以下を一覧にしてください。
1. webs2s.appsflyer.comへのすべての呼び出し箇所。/eventの呼び出しと、使用していれば/setcuidの呼び出しも含めます。
2. 各呼び出しで設定しているフィールド(customerUserId、afUserId、eventName、eventValue、eventRevenue、timestamp、referrer、userAgent、ipなど)と、それぞれの値の取得元。
3. 200 OKのレスポンスを基準とするエラー処理と監視。
4. 再試行、バッチ処理、キューイングの動作。
一覧を提示し、私の確認を得てから次に進んでください。
## エンドポイントと認証の変更点
| | PBA Web-S2S(旧) | 新しいS2S API |
|---|---|---|
| ベースURL | https://webs2s.appsflyer.com | https://events.appsflyer.com |
| イベントの呼び出し | POST /v1/{bundleId}/event | POST /v2.0/s2s/inapps/app/web/{appId} |
| 訪問の呼び出し | 非対応 | POST /v2.0/s2s/visits/app/web/{appId} |
| 識別子の関連付けの呼び出し | POST /v1/{bundleId}/setcuid | なし。すべての呼び出しのuser_idオブジェクト内に識別子を含めて送信 |
| パス内のアプリ識別子 | bundleId(ブランドバンドルID) | appId=Webの統合アプリID("website-{domain}") |
| 認証 | JSON本文内のwebDevKey | S2S APIキーを含むAuthorizationヘッダー |
| コンテンツタイプ | application/json | application/json(省略すると415) |
| 成功時のレスポンス | 200 OK | 202 Accepted |
## ペイロードのフィールド対応表
| PBAのフィールド | 新しいフィールド | 注意 |
|---|---|---|
| customerUserId | user_id.customer_user_id | user_idオブジェクト内にネストされます。 |
| afUserId | user_id.appsflyer_id | user_idオブジェクト内にネストされます。 customer_user_idかappsflyer_idの少なくとも一方を送信し、ユーザーを識別できた場合は両方を送信してください。 |
| webDevKey | (削除) | 認証はAuthorizationヘッダーに移り、アプリはパス内のappIdで識別されます。 |
| eventType(常に"EVENT") | (削除) | エンドポイント(/inappsか/visitsか)によって種類が決まります。 |
| eventName | event_name | 1〜64文字。@ = + -は使用できません。 |
| timestamp(Unixミリ秒) | timestamp(Unixミリ秒) | 形式は同じです。すべての呼び出しでの設定を推奨します。省略した場合は、AppsFlyerが受信時刻を使用します。 |
| eventValue | event_value | 自由形式で、custom_parametersサブオブジェクトに対応します。 |
| eventRevenue | event_revenue | 任意になりました(PBAではダッシュボード表示に必須)。 |
| eventRevenueCurrency | event_revenue_currency | 任意になりました(PBAではダッシュボード表示に必須)。 |
| referrer | http_referrer | 名称変更。 |
| userAgent | user_agent | 名称変更。 |
| ip | ip | 変更なし。 |
| (新規) | event_url | 訪問では必須、イベントでは任意です。 |
| (新規) | customer_dedup_id | 別のソース(Web SDKなど)から届く同じイベントとの重複を排除します。 |
| (新規) | email_hashed, phone_number_hashed, phone_number_e164_hashed, first_name_hashed, last_name_hashed | 識別子情報を補完するため、正規化した値をSHA256でハッシュ化したもの(64文字の小文字16進数)。 |
## 動作の変更点と注意事項
1. **appIdは統合アプリIDであり、"Web SDK ID"ではありません。** AppsFlyerのアプリ設定ページに表示される"Web SDK ID"はUUIDです(SDKを継続使用できるよう維持されている、従来のWeb Dev Key)。 S2Sのパスには必ず統合アプリID("website-{domain}")を設定し、そのUUIDを使用しないでください。 401の"app not found"は通常、パス内のappIdの誤り、またはAuthorizationヘッダーの欠落・無効を示します。
2. **成功時は200ではなく202。** ヘルスチェック、再試行、アラートをそれに合わせて更新してください。
3. **旧エンドポイントのレスポンスで検証しない。** 旧エンドポイントが引き続き200を返しても、Web Performance Measurementにデータが届いた証拠にはなりません。新しいWebアプリのデータに、イベントが実際に表示されることを必ず確認してください。
4. **setcuidの処理をすべて削除。** 各イベント・訪問のuser_idオブジェクト内に識別子を含めて送信します。
5. **イベントの前に訪問。** このシステムは、ユーザーのイベントに先立って訪問があることを前提としています。過去の訪問がないユーザーのイベントはオーガニックに分類されます。訪問はWeb SDK、または新しい/visitsエンドポイントから送信します。
6. **バッチではなくリアルタイムに送信。** 各イベントと訪問を発生時に、できれば発生から30分以内に送信してください。イベントが発生したUTC日の終了から30分を過ぎて届いたデータも受け付けられますが、イベントの発生時刻が受信時刻に置き換えられ、正確なアトリビューションができなくなります。必ずtimestampを送信してください。なお、説明に出てくる約30分のアトリビューションの遅延は、AppsFlyerのサーバー側で行う別の保留処理であり、こちらで実装する必要はありません。
7. **すべてをサーバー側で実装する場合(訪問も送信する場合)。** Web SDKを使用しない場合、Webユーザーの識別子は自社サーバーで管理します。初回訪問者に安定したIDを発行し、サーバー設定のファーストパーティHTTP Cookieとして保存してください(JavaScriptではなくSet-Cookieヘッダーを使用。SafariではJavaScriptのCookieは約7日で制限されるため)。このIDをすべてのリクエストで再利用し、user_id.appsflyer_idとして送信します。訪問のペイロードにはevent_urlが必須です。アトリビューションの精度のため、ip、user_agent、http_referrerも含めることを推奨します。
8. **SDKとS2Sの併用。** 両方から同じイベントを送信する場合は、customer_dedup_idを設定し、AppsFlyerが1件だけ保持するようにしてください。
## ステップ2:構築
1. 設計を提案してください。新しいクライアント・モジュール、設定(ベースURL、appId、シークレットマネージャーでのAPIキー保存。ハードコードは禁止)、イベント用ペイロードの生成処理(対象に含める場合は訪問用も)、202に対応するレスポンス処理と再試行処理を含めます。
2. 私の承認後、既存の規約に従って実装してください。
3. 一覧の全フィールドを上記のペイロード対応表に従ってマッピングし、現在送信していて新方式に対応するものがないフィールドは明示してください。
## ステップ3:検証
1. テストイベントを送信し(対象に含める場合は訪問も)、202が返ることを確認してください。
2. AppsFlyerの新しいWebアプリで、テストデータがダッシュボードまたはData Lockerに表示されることを確認してください。HTTPレスポンスではなく、これが実際の成功の判断基準です。
3. イベント名が新しい制限に従っていることを確認してください(1〜64文字、@ = + -は使用不可)。
4. 旧サービスと並行稼働する場合は、切り替え前に数日間、新旧のイベント数を比較してください。その後、setcuidを含む旧方式の呼び出しを廃止します。