KappSナレッジベース · ブログ

Google PlayInstall Referrer API 2026年版:アトリビューションデータと接続状態

ブログ ガイド

インストールアトリビューションは、すべての有料インストールが依存する唯一の計測であり、Google Playでは小さな単一のインターフェース、Install Referrer APIから得られます。これはダッシュボードの機能でも、数字をメールで送ってくれるものでもありません。Playがインストール時に記録したリファラル情報を一度だけアプリに渡すので、その後の保存と突き合わせは自分の仕事です。このチュートリアルでは、APIが返す内容、接続方法、レスポンスの読み方、多くのチームが手遅れになってから知る90日ルール、そして各接続状態への対処まで、全体の流れを解説します。

以下の内容はすべて、Install Referrer APIとPlay Install Referrer Client Libraryに関するGoogle自身のリファレンスページに基づいており、いずれも2026-10-27に確認したものです。

ステップ1 — 設計する前にAPIが何を返すかを正確に把握する

APIはPlayストアアプリが記録した紹介コンテンツを取得します。ドキュメント上のペイロードは限定的かつ具体的です:

  • インストール済みパッケージのreferrer URL;
  • リファラークリックのタイムスタンプ(秒単位) — クライアント側・サーバー側の両方で取得可能;
  • インストールが開始された時刻のタイムスタンプ(秒単位) — これもクライアント側とサーバー側の両方で
  • 初回インストール時点のアプリバージョン;
  • ユーザーが過去7日間にアプリのインスタント体験とやり取りしたかどうか。

前提となる要件は2つあります。APIはデバイス上のPlay Storeアプリによって公開されており、Play Store 8.3.73以降を実行しているデバイスは自動的にアクセスできます。さらにGoogle Play Consoleアカウントも必要です。内部的にはAPIはAIDLインターフェースであり、KotlinおよびJavaのデベロッパーは生のAIDLではなくクライアントライブラリのラッパーを使用することが想定されています。

設計上の帰結:これはクリックのタイムスタンプとインストール開始のタイムスタンプを伴う初回インストールのアトリビューションです。レスポンスにマルチタッチのチェーン、ビュースルー、クロスデバイスのグラフはありません。レポートモデルがこれらのいずれかを前提としているなら、そのデータは別の場所から取得する必要があります。

ステップ2 — クライアントライブラリを追加する

アプリモジュールのbuild.gradleに依存関係を追加します。クライアントライブラリのページに記載されているバージョンは2.2です。

dependencies { ... implementation "com.android.installreferrer:installreferrer:2.2" }

モジュールがKotlin DSLで設定されている場合、同じ座標はimplementation("com.android.installreferrer:installreferrer:2.2")で追加します。他には何も不要です — マニフェストレシーバーも、パーミッションも、Play Consoleのトグルもありません。このライブラリが置き換えるのは旧来のブロードキャストレシーバー方式です。両方の経路を併用しないでください。

ステップ3 — Playストアアプリに接続する

接続は非同期で、壊れた実装のほとんどはまさにこの一点から始まります。公式に示されている手順は次のとおりです。InstallReferrerClient.newBuilder(this).build()でクライアントを生成し、startConnection()を呼び出し、結果を受け取るInstallReferrerStateListenerを渡します。

referrerClient = InstallReferrerClient.newBuilder(this).build() referrerClient.startConnection(object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { InstallReferrerResponse.OK -> { /* 接続確立 */ } InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* このPlayストアアプリではAPIを利用できません */ } InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* 接続を確立できませんでした */ } } } override fun onInstallReferrerServiceDisconnected() { /* 次のリクエストの前にstartConnection()を再度呼び出してください */ } })

コールバックの契約は文字どおりに読んでください。OKは接続に成功し、処理を進めてよいことを意味します。FEATURE_NOT_SUPPORTEDは、その端末のPlayストアアプリでAPIが利用できないことを意味します。古い、または非標準のストアビルドによるもので、あなたのコードのバグではありません。SERVICE_UNAVAILABLEは接続自体が確立できなかったことを意味し、これはタイミングの問題であって判定ではありません。

切断は例外ではなく想定内です。Google自身の注記によると、Play Storeサービスがバックグラウンドで更新中の場合にクライアントが接続を失うことがあり、以降のリクエストの前にstartConnection()を再度呼び出して接続を再開する必要があります。つまりリスナーは一度きりのものではなく、自分で駆動するステートマシンとして扱うべきです。

ステップ4 — リファラー情報を確認する

接続後、getInstallReferrer()は同期的に呼び出され、ReferrerDetailsオブジェクトを返します。各フィールドはステップ1に記載のペイロードと1対1で対応します。

val response: ReferrerDetails = referrerClient.installReferrer val referrerUrl: String = response.installReferrer val referrerClickTime: Long = response.referrerClickTimestampSeconds val appInstallTime: Long = response.installBeginTimestampSeconds val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

このうち2つは見た目以上に有用です。referrerClickTimestampSecondsとinstallBeginTimestampSecondsを使えば、キャンペーンごとのクリックからインストールまでの差分を計算できます。差分が大きい場合は通常、広告ではなくストアページでユーザーを失ったことを意味します。googlePlayInstantParamは、過去7日以内にインスタント体験からインストールされたかどうかを示す、レスポンス内で唯一のインスタントアトリビューションのシグナルです。

ステップ5 — 90日間の窓を守り、一度だけ呼び出す

チームの履歴データを失わせる一文はこれです:インストールリファラー情報は90日間利用可能で、アプリが再インストールされない限り変更されません。続くGoogleのガイダンスも同様に明快です — 不要なAPI呼び出しを避けるため、インストール後の初回実行時に一度だけAPIを呼び出してください。

90日間は保存の許諾ではありません。Playから値を取得できる期間であり、後日のセッションで遅延して読み取るだけのアプリには厳しい期限があります。インストール後の初回起動時に読み取り、永続化してください。アプリを再インストールしない限り値は変わらないため、更新ループには何の意味もなく、呼び出しが増えるだけです。

終了したら接続を閉じてください。クライアントでendConnection()を呼び出します。Googleの理由は明確です——接続を閉じることで、デバイス上のリークやパフォーマンス問題を防ぎます。

ステップ6 — レスポンスコードで分岐し、盲目的にリトライしない

初回起動時のアトリビューション読み取りはユーザーの初回体験のクリティカルパス上にあるため、失敗時のポリシーはコードと同じくらい重要です。実用的なマッピング:

  • OK — 読み取り、永続化し、endConnection()を実行する。以降の起動時に再読み取りしないこと。
  • SERVICE_UNAVAILABLE — 「今はできない」として扱います。何も保存せず、最初の画面をブロックせず、90日間の期間内で次回以降の起動時に再試行してください。
  • FEATURE_NOT_SUPPORTED — この端末にAPIが存在しません。自社リンクが持つキャンペーン識別子にフォールバックし、読み取りが非対応だったことを記録してください。そうしないとレポートがオーガニックとして黙って計上してしまいます。
  • 切断済み — 次のリクエストの前にstartConnection()で再起動してください。クライアントがまだ生きていると仮定しないでください。

4つのルールすべてに優先するエンジニアリング原則が1つあります。アトリビューションが初回起動時のUXを妨げてはならず、読み取り失敗時に誤って「オーガニック」のアトリビューション行を書き込んではならないということです。「データなし」と「オーガニック」の違いこそが、インストールレポートの照合が合わなくなるまさにその地点です。

ステップ7 — リファラー文字列を信頼できない入力として扱う

クライアントライブラリはリファラー値を文字列として返します。これはプラットフォームから配信されるものの、アプリの外部に由来する値であることに変わりはないため、外部入力に対する通常の衛生管理が適用されます。防御的にキーと値のペアへパースし、長さを制限し、検証せずにURL、ディープリンクのルート、データベースクエリへ埋め込まないでください。

実際にはこういうことです。値をデコードし、ドキュメント化された区切り文字で分割し、実際に認識できるキャンペーンキーだけをホワイトリストに入れ、それ以外はすべて捨てます。そして課金や収益の入力になる前に、自社のサーバー側イベントと突き合わせます。アトリビューションのデータはどのチャネルに予算を配分するかを決めるものです。検証されていない文字列がお金を動かせるようではいけません。

リファラー文字列を広告ネットワークやMMPに転送する場合は、パイプラインのリリース後ではなく監査の前に、Play データセーフティの宣言とプライバシーポリシーがその共有をすでにカバーしているか確認してください。アトリビューションの仕組みはデータ収集であり、宣言はそれを記述していなければなりません。

ステップ8 — APIが教えてくれないことを書き留める

アトリビューションの争いのほとんどは、正しいレスポンスに間違った期待を寄せることから生じます。2つのリファレンスページから、正直な限界は次のとおりです:

  • Play Store 8.3.73未満のデバイスにはAPIがそもそも存在しません——フォールバックを計画してください。FEATURE_NOT_SUPPORTEDはログに記録して忘れるエラーではなく、現実に起こりうる結果です。
  • この値は初回インストール時に固定され、アプリを再インストールしない限り変わりません。そのため、再エンゲージメント、アップグレード、後発のキャンペーン接点を表すことはできません。
  • 取得可能期間は90日で終了します — その期間内に保存しなかったものは失われます。
  • インスタント体験フラグが対象とするのは7日間の遡及のみ。
  • これはPlayからのインストールに対するデバイスおよびアカウントレベルのシグナルであり、ユーザー識別情報ではなく、デバイス間でインストールを重複排除するものでもありません。

これら5つの制約は、アトリビューションスキーマと同じドキュメントに記載しておきましょう。キャンペーンレポートと収益レポートが食い違うとき、その原因は通常この5つのいずれかであり、クライアント側のバグではありません。

出典:Android Developers — Google Play Install Referrer API(developer.android.com/google/play/installreferrer):ペイロードのフィールド、Play ストア8.3.73以降の要件、AIDLインターフェース、Play Consoleアカウントの要件。Android Developers — Play Install Referrer Library(developer.android.com/google/play/installreferrer/library、最終更新2026-10-23):依存関係のバージョン2.2、接続フローとレスポンスコード、getInstallReferrer()とReferrerDetailsのフィールド、90日間の利用可能期間に関する注記、インストールごとに1回という推奨事項、そしてendConnection()。いずれも2026-10-27に確認。Googleはキャンペーン別のアトリビューション率やストア側のレイテンシ数値は公開しておらず、本記事でも推測していません。

デベロッパーアカウントを大規模に運用中ですか? 運用面は当社が対応します。

クリックしてファイルを選択 · 右クリック→貼り付け、またはCtrl/⌘+Vでスクリーンショットを貼り付け

このボックスにファイルをドラッグすることもできます。

ご提供いただいたメールに返信します。お客様の情報はKappS内に留まります。

✔ 送信済み

メッセージを受け付けました。24時間以内に返信します。


← 編集に戻る