AndroidにおけるInstall Referrer APIについてのまとめ
Install Referrer APIとは
リファラー情報をAndroid側で取得するためのAPI。かつてはAPIではなくBroadcastで取得する方法があったが今はこの１つのみ。
公式に記載の通り、Play Storeからインストール後90日以内はアプリを再インストールしない限りは同じリファラー情報が返ってくる。Broadcastの時と違ってインストール直後に..という機能は備わっていないので、もしインストール直後初回だけInstal Referrer APIから取得したいならPreferenceなどの値（初回かどうか）に応じての工夫してあげる必要がありそう。
Install Referrer APIを用いた実装例
公式にある通り、リファラー情報はInstallReferrerStateListener#onInstallReferrerSetupFinishedで拾えるのでsuspendCancellableCoroutineを使うと良さげ。以下は改めてChatGPTで作成したサンプル。（このまま利用していないのでエラーの箇所あったらすみません、基本はこの方針で問題ないです）
suspend fun getInstallReferrer(context: Context): String? = suspendCancellableCoroutine { continuation ->
val referrerClient = InstallReferrerClient.newBuilder(context).build()
val listener = object : InstallReferrerStateListener {
override fun onInstallReferrerSetupFinished(responseCode: Int) {
when (responseCode) {
InstallReferrerClient.InstallReferrerResponse.OK -> {
val response = referrerClient.installReferrer
val referrerUrl = response.installReferrer
continuation.resume(referrerUrl)
referrerClient.endConnection()
}
else -> {
continuation.resume(null)
referrerClient.endConnection()
}
}
}
override fun onInstallReferrerServiceDisconnected() {
continuation.resume(null)
referrerClient.endConnection()
}
}
referrerClient.startConnection(listener)
continuation.invokeOnCancellation {
referrerClient.endConnection()
}
}
ちなみにresponseCodeをOK以外の値が返ってくるケースを動作確認したい場合はデバイス（エミュレータでもOK）の設定からPlayStoreを無効にすればOK。
開発環境でのリファラー情報
通常はPlayStoreへの遷移リンクに付与されたクエリパラメータがリファラー情報として渡ってくるが、開発環境（= PlayStoreに公開されているアプリケーションIDとは一致しない）の場合は常にutm_source=google-play&utm_medium=organicという固定値のリファラー情報が返ってくる。
本番環境でのリファラー情報とテスト方法
リファラー情報が付与されたPlayStore遷移リンク押下 > PlayStoreでインストール > アプリ起動 > Install Referrer APIで取得となるわけなので、
- リファラー情報を付与したURLの作成
- PlayStoreでインストール（の代わりにapkでインストール）
- インストールしたアプリを起動
のステップを踏むことで動作確認もできる。ただしテストする際はPlayStoreに公開されているアプリケーションIDのapkが必要なので本番向きに接続していいなら署名付きでapkを作成、あるいはアプリからサーバーへの接続先だけ手動で開発向きにして署名付きでapkを作成するなどの工夫が必要。
リファラー情報を付与したURLの作成
公式のリンク作成サイトで作成することもできるが特に利用必須ではない。ただ正しい形式になっているので手動で作成する場合は以下は必須なので注意
- アプリケーションID（PlayStoreの該当アプリ画面への遷移に必要）
-
&referrer=（これがないとリファラー情報として認識してくれない様子） - ad network
- campaign source
また、作成サイトで生成されたリンクを見るとわかるようにUTF-8でEncodeされた状態にしておくこと。
例としては以下。
https://play.google.com/store/apps/details?id=jp.co.test&referrer=utm_source%3Dgoogle%26anid%3Dadmob
→ 後半をDecodeするとid=jp.co.test&referrer=utm_source=google&anid=admob
Install Referrre API、つまりonInstallReferrerSetupFinishedで取得した時点でDecodeされている。今回のリンクだとval referrerUrl = utm_source=google&anid=admobという値として受け取ることになる。他のリファラー情報も連結されて１つのStringとして受け取り、連結順はURLに連結されている順のまま。注意点としてはリファラー情報は不正な形式でも設定して受け取ることができるのでutm_source=googleの形式にならずにutm_sourceだけ取得する場合もあるため、=などがない場合のハンドリングも考えた方が良い。（= 不正な値はスキップで）
気になるポイント: リファラー情報に関わらない、任意のクエリパラメータも追加したらInstall Referrer APIで取得できるか？
試した限りできる。ただし余計な&などをEncodeしないままで付与しないように注意。最終的に必須だったutm_sourceが見つからないとリファラー情報として判断されなくなったような。。
PlayStoreでインストール（の代わりにapkでインストール）
本番と同じアプリケーションIDのapkを用意したら、まずは先ほど作成したリンクでPlayStoreの画面に遷移する。今は「インストール」が表示されていて、そこでadb install -r <apkのpath>でインストールする（-rオプション不要だったかも？）。Androidのバージョンによるが「インストール」が消えてインストールされている状態になるはずでそうなればOK。そうならない場合はPlayStoreのアプリケーションIDと一致していないと思われる。
インストールしたアプリを起動
Stack overflowなどにはPlayStoreの「開く」を押さないとの情報があったが試した限りだと起動方法は特に指定はなく、通常通りアプリアイコンを押下して起動でOK。ちなみにそのあとアプリをアンインストールしてそのままapkで再度インストールして起動すると固定値のリファラー情報が返ってきたことを確認できたのでしっかり機能していた。
Discussion