モバイルWebからアプリインストールへのトラッキングパラメータの引き継ぎ方法

モバイルWebサイトからストアインストールへトラッキングパラメータを引き継ぐには？ モバイルWebサイトから新規インストールされたアプリへトラッキングパラメータを引き継ぐには、OpoInstall Web JS SDKを読み込み、許可リスト（Allowlist）に登録されたURLパラメータをキャプチャし、アプリ初回起動時にネイティブSDKを通じて対象のアトリビューションデータを復元するフローが必要です。

アプリストアのダウンロードを介したパラメータの連携は、ユーザーがモバイルランディングページからアプリストアへ遷移し、その後インストールしたアプリを起動するまでの間に、対象となるWeb URLパラメータを保持するプロセスです。Web SDKでキャンペーンや参照元のコンテキストをキャプチャし、プラットフォームがサポートする仕組みや遅延復元サービスを通じて、ネイティブアプリで利用可能な状態にします。復元は、プラットフォーム、SDKの設定、利用可能なマッチングシグナル、およびプライバシー要件に依存します。

Web-to-Storeアトリビューションのギャップ：アプリストア間のプラットフォーム障壁

切断の壁：OSのサンドボックスがブラウザのコンテキストを隔離する仕組み

Webアナリティクスでは一般的に、UTMタグ（utm_source、utm_medium、utm_campaign）、gclidやfbclidなどの広告クリック識別子、およびカスタム参照パラメータを含むURLクエリ文字列が利用されます。

Webサイト内では、ブラウザAPIやファーストパーティ分析システムがこれらの値をキャプチャし、許可された分析やキャンペーンワークフローに利用可能です。

問題が発生するのは、ユーザーがブラウザを離れ、アプリストアのインストールプロセスに移行したときです。ブラウザと新規インストールされたネイティブアプリは、それぞれ独立した環境で動作します。ブラウザのCookie、セッションストレージ、ページURLパラメータは、インストール後に自動的にアプリ内部で利用可能になるわけではありません。

そのため、開発者はストアがサポートする参照メカニズムや、遅延パラメータ復元ワークフローを用いて、インストール前のコンテキストとインストール後のアプリセッションを紐付ける必要があります。

プラットフォーム別の仕様：Apple App StoreとGoogle Playストアの取り込みの違い

モバイルアプリストアは、参照コンテキストの引き継ぎに対してそれぞれ異なるアプローチをサポートしています。

• Apple App Store (iOS): App Store経由の標準的なインストールでは、外部の任意のURLクエリパラメータが自動的に新規アプリの初回起動環境へ引き継がれることはありません。Appleのプライバシー要件に従いつつ、遅延復元サービスやユーザー主導のワークフローを通じて、対象となるコンテキストを復元できる場合があります。
• Google Play Store (Android): Googleは公式の「Google Play Install Referrer API」を提供しています。適切に構築されたGoogle Play参照フローを使用する場合、インストールされたアプリは、参照元文字列や関連するタイムスタンプを含む、サポート対象の参照メタデータを取得できます。

これらのメカニズムは互換性があるものとして扱うべきではありません。Google Playはストアレベルの公式参照インターフェースを提供しますが、iOSにおける任意の遅延パラメータ復元には、個別に設計されたポリシー準拠のメカニズムが必要です。

チャネルROI計算における未属性インストールトラフィックのビジネス的影響

Web訪問とアプリインストール間でキャンペーンパラメータが欠落すると、分析システムがインストールを元のキャンペーンと正しく関連付けられない可能性があります。

これにより、未属性のインストールが発生し、獲得レポートの不完全さや、ROI（投資利益率）やCAC（顧客獲得単価）の不正確な計算を招く恐れがあります。

また、パラメータの欠落はオンボーディング体験にも影響します。例えば、Web参照リンクに招待者IDやプロモーションコードが含まれている場合：

https://example.com/download?inviter_id=USR_1024
https://example.com/download?promo_code=WELCOME50

アプリがこれらの値を復元できない場合、ユーザーは手動で再入力する必要があります。

ただし、参照元やプロモーション値が復元されたとしても、自動的に報酬が承認されるわけではありません。アプリのバックエンドは、対象資格、利用制限、該当するビジネスルールを独自に検証する必要があります。

ストア対応型と遅延パラメータメカニズム：Apple App StoreとGoogle Playの比較

Google Playストア：ネイティブInstall Referrer APIの活用

Androidでは、Google Play Install Referrer APIが、サポート対象のインストール参照メタデータを取得するための公式メカニズムを提供しています。

Google PlayのダウンロードURLには、エンコードされたreferrerパラメータを含めることができます：

https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dfacebook%26inviter_id%3DUSR_1024

このURL例において、エンコードされた参照値は以下を表します：

utm_source=facebook&inviter_id=USR_1024

インストール後、ネイティブAndroidアプリはInstall Referrer Clientを使用して、Google Playから利用可能な参照情報を取得できます。

OpoInstall Web SDKの特定のリリースが、このようなURLを自動生成、修正、または管理するかどうかは、展開されているドキュメントと動作を確認する必要があります。Googleの公式APIが存在することが、サードパーティSDKの内部実装を保証するものではありません。

Apple App Storeの境界：ネイティブクエリパラメータを伴わない標準的なストアリダイレクトの処理

Apple App Storeは、任意のWebクエリパラメータを新規アプリの初回起動コールバックへ直接転送しません。

そのため、遅延復元ワークフローでは、ストアリダイレクト前に許可されたキャンペーン情報をキャプチャし、ネイティブアプリ起動時に該当コンテキストを要求するプロセスが必要になります。

SDKベースのワークフローでは、ベンダーが文書化している機能と、実際に使用されているSDKのバージョンによるマッチング手法を区別する必要があります。

マッチングやデータ収集手法は、Appleのプライバシーポリシーを遵守しなければなりません。特に、アトリビューション実装において、禁止されているデバイスフィンガープリントへの依存や、ATT（App Tracking Transparency）許可があれば禁止されているマッチング手法が許容されると見なしてはなりません。

ユニバーサルリンクは、インストール済みのアプリへの誘導には役立ちますが、それ単体では、任意のWebクエリパラメータがApp Storeの新規インストールを越えて存続することを保証するものではありません。

クロスプラットフォームのアーキテクチャ乖離：統一パラメータ契約の構築

AndroidとiOSでプラットフォームの仕組みが異なる場合でも、アプリは復元された値を共通のアプリレベルスキーマに正規化できます。

例：

{
  "utm_source": "facebook",
  "utm_medium": "paid_social",
  "utm_campaign": "summer_sale",
  "inviter_id": "USR_1024",
  "promo_code": "WELCOME50"
}

このJSONオブジェクトはアプリ定義の正規化パラメータ契約であり、すべてのOpoInstall SDKリリースから保証されるリテラルなレスポンス形式ではありません。

アプリはこれらのフィールドを以下の2つのカテゴリに分類すべきです：

• マーケティングアトリビューション: utm_source、utm_medium、utm_campaign
• 参照およびプロモーションアクション: inviter_id、promo_code

マーケティングアトリビューションは許可された分析パイプラインへ送信可能です。一方、参照やプロモーションのアクションには、アプリが特典を付与する前に、サーバーサイドによる独立した承認が必要です。

ストアリダイレクトを橋渡しするコンテキストペイロードキャッシュの役割

遅延復元サービスは一般的に、インストールコンテキストの保持期間を限定しています。

適用される保持ウィンドウ、復元動作、マッチングの可用性は、使用するサービス、SDK設定、ネットワーク状態、プラットフォームの制限、およびプライバシー要件に依存します。

エンジニアリングチームは、サポートされていない精度指標を鵜呑みにせず、独自のインストールコホートを使用して復元結果を測定すべきです。

プライバシーを意識した遅延コンテキストアーキテクチャとプラットフォームの境界

iOSにおけるシステムペーストボードの境界：透明性バナーとUIPasteControlによる意図の明示

一部の過去の遅延リンク実装では、アプリケーション間で一時的なコンテキストを運ぶためにシステムペーストボードが使用されていました。

しかし、iOSはアプリ間のペーストボードアクセスを制限し、ユーザーに可視化しています。

• iOS 14: 他のアプリからコピーされた内容を読み取る際、ペーストボードアクセスの通知バナーが表示される場合があります。
• iOS 16以降: プログラムによる特定のペースト操作は、許可プロンプトをトリガーする可能性があります。UIPasteControlのようなコントロールは、ユーザーが開始したペースト操作をサポートします。

したがって、一般的なペーストボードへのアクセスを、不可視かつ制限のないインストールパラメータ転送チャネルとして扱ってはなりません。

ペーストボードに関連する機能を使用するアプリは、ユーザーの期待に沿った操作を行い、許可が拒否された場合やコンテンツが存在しない場合を適切に処理する必要があります。

Androidにおけるフォアグラウンド・クリップボードの制限：ナビゲーション制約と自動消去

Androidもまた、クリップボードへのアクセスに制限を設けています。

• Android 10以降: アプリがフォアグラウンドにない場合、プラットフォーム定義の例外を除き、クリップボードアクセスは制限されます。
• Android 13以降: クリップボード関連のUIフィードバックを提供し、クリップボード内容の自動消去動作を行います。

アプリは、クリップボードデータがサイレントに取得できる、あるいは永続的に利用可能であると想定してはなりません。

クリップボードアクセスはオプションとし、アトリビューションの主要なチャネルと見なすのではなく、適切なユーザー向けワークフローに限定すべきです。

Appleのユーザープライバシーとデータ利用ポリシーの厳守：デバイスフィンガープリントの禁止

Appleは、デバイスや環境特性の組み合わせを通じてユーザーやデバイスを識別するデバイスフィンガープリントを禁止しています。

実装においては、Appleのポリシーに違反する形で、IPアドレス、ユーザーエージェント情報、表示特性、その他のデバイス信号の組み合わせから、永続的または確率的な識別子を構築してはなりません。

App Tracking Transparencyの許可を得ているからといって、禁止されたフィンガープリント手法が許容されるわけではありません。

サードパーティの遅延パラメータ復元サービスを利用する場合、開発者は当該SDKが実際にどのようなデータを収集し、どのようなマッチングを行っているか、またプライバシー開示やプラットフォームポリシーの要件を満たしているかを検証する必要があります。

プライバシーを意識した統合では、データ最小化、透明性の高いユーザー操作、およびサポートされたプラットフォームメカニズムを優先すべきです。

セキュリティと信頼の境界：パラメータライフサイクルの管理とサーバー承認

復元されたすべてのパラメータは、信頼できない入力（Untrusted input）として扱わなければなりません。

マーケティングタグや参照トークンは、編集可能なURLや信頼できないクライアントリクエストから発生する可能性があります。パラメータが存在するということだけで、キャンペーンが正当であることや、ユーザーが報酬を受ける資格があることを証明するものではありません。

アプリは以下の原則に従うべきです：

• 許可リスト値: 明示的にサポートされたキーと境界のある値のみを受け入れる。
• アトリビューションと承認の分離: UTM値はトラフィックの起源を説明するものであり、それ自体がプロモーションの利益を独自に承認すべきではない。
• 時間制限付きの保留レコード: アプリ側で定義した有効期限内に従い、処理に必要な情報のみを保持する。
• 保護されたストレージ: 必要に応じてAndroid KeystoreやiOS Keychain Servicesなど、保留中トークンの機密性に適したストレージを使用する。
• 独立した配信結果: マーケティングパラメータと報酬パラメータの両方を含むレコードについては、それぞれ必要な結果を個別に追跡する。
• サーバーサイドの報酬検証: 招待クレジット、割引など、同等の権限は認証されたアプリバックエンドによって承認されなければならない。
• 冪等（べきとう）な報酬適用: バックエンドはトランザクションレベルで冪等性を強制し、ビジネスレベルのユニーク制約を設けることで、繰り返し発生するクライアントリクエストによる特典の二重付与を防ぐ。

以下のコードは、パラメータの境界とホストアプリの統合責任を示しています。本番環境向けの完全なストレージ、分析、報酬トランザクションシステムを網羅するものではありません。

エンドツーエンドの実装：Webパラメータのキャプチャからネイティブへの復元

Webクエリパラメータのサニタイズ：HTMLブートストラップ、許可リストパース、Web JS SDK設定

ランディングページは、明示的にサポートされたクエリパラメータをキャプチャし、境界のあるペイロードとしてWeb SDKへ渡すことができます。

以下の例では、以下を示しています：

• 設定されたソースからのSDKの読み込み。
• 通常のHTTPSダウンロードフォールバックリンクの保持。
• サポートされているパラメータキーのみの受け入れ。
• 狭い文字ポリシーと長さポリシー外の値の拒否。
• SDKのダウンロードアクションとページボタンの接続。

SDKコンストラクタ、設定キー、メソッドはあくまで一例です。公開や展開の前に、最新のOpoInstall Web SDKリリースの署名を確認してください。

<!-- CODE_BLOCK_01: 代表的なHTMLブートストラップとWeb SDKの統合 -->
<!-- ファイル: landing_page.html -->

<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>アプリのダウンロード</title>
</head>
<body>
    <!-- 実際のHTTPSダウンロードまたはストアルーティングURLに置き換えてください。 -->
    <a
        id="download-app-btn"
        href="https://app.example.com/store-download"
    >
        アプリをダウンロード
    </a>

    <!-- 公式CDN URLがデプロイされたSDKバージョンと一致するか確認してください。 -->
    <script src="https://web.cdn.opoinstallcloud.com/openinstall.js"></script>

    <script>
    (function () {
        "use strict";

        function getSanitizedQueryParams() {
            var allowedKeys = new Set([
                "utm_source",
                "utm_medium",
                "utm_campaign",
                "inviter_id",
                "promo_code"
            ]);

            var validPattern = /^[A-Za-z0-9_.-]{1,64}$/;
            var result = Object.create(null);

            try {
                var query = new URLSearchParams(window.location.search);

                query.forEach(function (value, key) {
                    if (
                        allowedKeys.has(key) &&
                        validPattern.test(value) &&
                        !Object.prototype.hasOwnProperty.call(result, key)
                    ) {
                        result[key] = value;
                    }
                });
            } catch (error) {
                console.warn("URLパラメータをパースできませんでした。");
                return Object.create(null);
            }

            return result;
        }

        var downloadButton = document.getElementById(
            "download-app-btn"
        );

        // アンカーのhrefをブラウザの通常のフォールバックとして保持する
        if (!downloadButton) {
            return;
        }

        if (typeof OpenInstall === "undefined") {
            console.warn(
                "Web SDKが利用できません。ダウンロードリンクを使用します。"
            );
            return;
        }

        var customParams = getSanitizedQueryParams();

        try {
            new OpenInstall({
                appKey: "OPOINSTALL_APPKEY_PLACEHOLDER",
                data: customParams,

                onready: function () {
                    var sdkClient = this;

                    downloadButton.addEventListener(
                        "click",
                        function (event) {
                            try {
                                // 代表的なSDKメソッド。
                                // デプロイされたリリースの動作と非同期エラー
                                // ハンドリングを確認してください。
                                sdkClient.wakeupOrInstall();
                                event.preventDefault();
                            } catch (error) {
                                console.warn(
                                    "SDKアクションが失敗しました。ブラウザのフォールバックを使用します。"
                                );

                                // デフォルトのアンカーアクションを禁止しないでください。
                            }
                        }
                    );
                }
            });
        } catch (error) {
            console.warn(
                "Web SDKの初期化に失敗しました。フォールバックリンクを使用します。"
            );
        }
    })();
    </script>
</body>
</html>

値のポリシーとして、文字、数字、アンダースコア、ハイフン、ピリオドのみを許容し、最大64文字までに制限しています。

スペースやその他の文字が含まれる値は、このリファレンス実装では除外されています。UTM命名要件がより広範なチームは、すべてのURL値がサポートされると想定せず、フィールドごとに適切なスキーマを定義しテストしてください。

同様に、gclidやfbclidなどの広告クリック識別子は、一般的なWebアトリビューションの概念として議論されますが、このサンプル許可リストには含まれていません。これらをサポートするには、個別のデータ収集、保持、およびプライバシーレビューが必要です。

SDKが読み込めない、または初期化できない場合、フォールバックアンカーが利用可能な状態になります。SDK操作は非同期的に失敗する可能性があるため、本番環境の統合においてはSDKのドキュメント化されたエラーハンドリングとリダイレクト動作に従う必要があり、同期的なtry/catchだけでは不完全な非同期フォールバック戦略となります。

Androidネイティブ実装：SDKセットアップ、パラメータ検証、ホストアプリ契約

インストール後、AndroidアプリはネイティブSDKからサポート対象のパラメータを要求し、アプリ定義のレコードへ正規化できます。

以下のサンプルでは、責務を意図的に分離しています：

1. OpoInstall SDKはアプリのメインプロセスで初期化される。
2. ネイティブコールバックが候補となるペイロードを提供する。
3. アプリがペイロードを検証・正規化する。
4. アプリがホスト提供のストレージインターフェースを介してレコードを保存する。
5. ホスト提供の処理コンポーネントがマーケティングアトリビューションと報酬承認を調整する。
6. アプリは、そのコンポーネントが検証済み処理結果を報告した後にのみ、レコードを完了としてマークする。

重要： ホストインターフェースはアプリ定義の契約であり、OpoInstall APIではありません。この例では、ホストアプリが実装を提供する必要があります。安全でないフォールバックストレージ、シミュレーションされた分析配信、報酬承認のモック応答は含まれていません。

// CODE_BLOCK_02: 代表的なAndroid統合 (Kotlin)
// ファイル: CustomApplication.kt および MainActivity.kt
//
// OpoInstallのインポートとコールバックを展開されたAARと照合してください。
// パラメータ処理を行う前にホスト実装を提供する必要があります。

package com.example.app

import android.app.ActivityManager
import android.app.Application
import android.content.Context
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.os.Process
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.opoinstall.api.OpoInstall
import com.opoinstall.api.OpoData
import com.opoinstall.api.OpoError
import com.opoinstall.api.ResultCallBack
import org.json.JSONObject
import java.util.UUID

enum class ParamFetchState {
    NOT_STARTED,
    FETCHING,
    RECEIVED,
    APPLIED,
    REJECTED,
    NO_MATCH,
    RETRYABLE_FAILURE
}

data class PendingAttributionRecord(
    val utmSource: String?,
    val utmMedium: String?,
    val utmCampaign: String?,
    val inviterId: String?,
    val promoCode: String?,
    val idempotencyKey: String,
    val createdAt: Long,
    val expiresAt: Long
) {
    val hasAttributionData: Boolean
        get() = listOf(
            utmSource, utmMedium, utmCampaign
        ).any { !it.isNullOrEmpty() }

    val hasRewardData: Boolean
        get() = !inviterId.isNullOrEmpty() ||
                !promoCode.isNullOrEmpty()

    val hasAnyData: Boolean
        get() = hasAttributionData || hasRewardData

    fun isValid(): Boolean {
        val now = System.currentTimeMillis()
        val pattern = Regex("^[A-Za-z0-9_.-]{1,64}$")

        val values = listOf(
            utmSource, utmMedium, utmCampaign,
            inviterId, promoCode
        )

        val validFields = values.all {
            it == null || pattern.matches(it)
        }

        val validWindow =
            expiresAt > createdAt &&
            expiresAt - createdAt <= 48L * 60 * 60 * 1000 &&
            now >= createdAt &&
            now <= expiresAt

        val validId = try {
            UUID.fromString(idempotencyKey)
            true
        } catch (_: IllegalArgumentException) {
            false
        }

        return hasAnyData &&
               validFields &&
               validWindow &&
               validId
    }
}

// ホスト定義の安全な永続化契約
// 実装は欠落データとストレージ障害を区別し、必要に応じてアカウント紐付けを処理する必要がある。
interface PendingTransactionStore {
    fun save(record: PendingAttributionRecord): Boolean
    fun load(): PendingAttributionRecord?
    fun clear(): Boolean
}

// ホスト定義のコーディネーター。実装は、独立したテレメトリ/報酬確認、
// 冪等性、リトライ処理、トランザクション識別子のチェックに責任を持つ。
interface InstallParameterProcessor {
    fun process(
        record: PendingAttributionRecord,
        onComplete: (ProcessingOutcome) -> Unit
    )
}

enum class ProcessingOutcome {
    COMPLETED,
    REJECTED,
    RETRYABLE_FAILURE
}

// これらはアプリの依存関係であり、OpoInstall SDK APIではない。
object HostAppDependencies {
    var transactionStore: PendingTransactionStore? = null
    var parameterProcessor: InstallParameterProcessor? = null

    val isConfigured: Boolean
        get() = transactionStore != null &&
                parameterProcessor != null
}

class CustomApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        if (isMainProcess()) {
            OpoInstall.initialize(this)

            // ホストアプリはここで依存関係を構成する必要がある
            // 実際のDI/ブートストラップメカニズムを使用する。
            //
            // HostAppDependencies.transactionStore =
            //     hostProvidedProtectedStore
            //
            // HostAppDependencies.parameterProcessor =
            //     hostProvidedInstallParameterProcessor
        }
    }

    private fun isMainProcess(): Boolean {
        val manager = getSystemService(
            Context.ACTIVITY_SERVICE
        ) as ActivityManager

        val currentPid = Process.myPid()

        return manager.runningAppProcesses?.any {
            it.pid == currentPid &&
            it.processName == packageName
        } == true
    }
}

class MainActivity : AppCompatActivity() {

    private val mainHandler = Handler(Looper.getMainLooper())

    private var state = ParamFetchState.NOT_STARTED
    private var activeRecord: PendingAttributionRecord? = null
    private var processingInFlight = false

    private val transactionTtlMs =
        24L * 60 * 60 * 1000

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        startParameterFlow()
    }

    private fun startParameterFlow() {
        val store = HostAppDependencies.transactionStore
        val processor = HostAppDependencies.parameterProcessor

        if (store == null || processor == null) {
            Log.w(
                "OpoInstall",
                "ホストの依存関係が利用不可。処理を中断しました。"
            )
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        // 代表的なレコード復元
        // 本番のストレージは、読み込みエラーを保留レコードの不在とは別に報告すべき。
        val existingRecord = try {
            store.load()
        } catch (error: Exception) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (existingRecord != null) {
            if (existingRecord.isValid()) {
                activeRecord = existingRecord
                state = ParamFetchState.RECEIVED
                processRecord(existingRecord)
            } else {
                // 無効または期限切れのレコードは処理しない
                if (!store.clear()) {
                    state = ParamFetchState.RETRYABLE_FAILURE
                    return
                }

                requestInstallParameters()
            }
        } else {
            requestInstallParameters()
        }
    }

    private fun requestInstallParameters() {
        if (!HostAppDependencies.isConfigured) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (state == ParamFetchState.FETCHING ||
            state == ParamFetchState.APPLIED ||
            state == ParamFetchState.NO_MATCH ||
            processingInFlight
        ) {
            return
        }

        state = ParamFetchState.FETCHING

        // 代表的なSDKコールバック。
        // AARに対して署名を確認してください。
        OpoInstall.getInstance().getInstallParam(
            object : ResultCallBack<OpoData> {

                override fun onResult(opoData: OpoData?) {
                    mainHandler.post {
                        if (state != ParamFetchState.FETCHING) {
                            return@post
                        }

                        val rawData: Any? = opoData?.data

                        val payload = when (rawData) {
                            is String -> rawData
                            is JSONObject -> rawData.toString()
                            is Map<*, *> -> try {
                                JSONObject(rawData).toString()
                            } catch (_: Exception) {
                                null
                            }
                            else -> null
                        }

                        val record = payload?.let {
                            parseAndSanitizeRawPayload(it)
                        }

                        if (record == null) {
                            // 対象データが復元されなかった
                            // これは自然インストールである証明ではない。
                            state = ParamFetchState.NO_MATCH
                            return@post
                        }

                        val store =
                            HostAppDependencies.transactionStore

                        if (store == null ||
                            !HostAppDependencies.isConfigured
                        ) {
                            state = ParamFetchState.RETRYABLE_FAILURE
                            return@post
                        }

                        activeRecord = record

                        // 保存が失敗した場合、確実な復元とは見なさない
                        val saved = try {
                            store.save(record)
                        } catch (_: Exception) {
                            false
                        }

                        if (!saved) {
                            Log.w(
                                "OpoInstall",
                                "保留レコードを永続化できませんでした"
                            )
                            state = ParamFetchState.RETRYABLE_FAILURE
                            return@post
                        }

                        state = ParamFetchState.RECEIVED
                        processRecord(record)
                    }
                }

                override fun onError(error: OpoError?) {
                    mainHandler.post {
                        if (state == ParamFetchState.FETCHING) {
                            Log.w(
                                "OpoInstall",
                                "インストールパラメータの取得に失敗しました"
                            )
                            state = ParamFetchState.RETRYABLE_FAILURE
                        }
                    }
                }
            }
        )
    }

    private fun parseAndSanitizeRawPayload(
        rawJson: String
    ): PendingAttributionRecord? {
        return try {
            if (rawJson.length > 4096) return null

            val json = JSONObject(rawJson)
            val pattern = Regex("^[A-Za-z0-9_.-]{1,64}$")

            fun field(key: String): String? =
                (json.opt(key) as? String)?.takeIf {
                    pattern.matches(it)
                }

            val now = System.currentTimeMillis()

            val record = PendingAttributionRecord(
                utmSource = field("utm_source"),
                utmMedium = field("utm_medium"),
                utmCampaign = field("utm_campaign"),
                inviterId = field("inviter_id"),
                promoCode = field("promo_code"),
                idempotencyKey = UUID.randomUUID().toString(),
                createdAt = now,
                expiresAt = now + transactionTtlMs
            )

            record.takeIf { it.isValid() }
        } catch (_: Exception) {
            null
        }
    }

    private fun processRecord(
        record: PendingAttributionRecord
    ) {
        val processor = HostAppDependencies.parameterProcessor
        val store = HostAppDependencies.transactionStore

        if (processor == null || store == null ||
            !record.isValid()
        ) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        if (processingInFlight) return

        processingInFlight = true

        // ホストプロセッサはすべての必要なチャネル固有の成果が
        // 確認されるまでCOMPLETEDを報告してはならない。
        processor.process(record) { outcome ->
            mainHandler.post {
                // 取って代わられた、または古いトランザクションは無視する
                if (activeRecord?.idempotencyKey !=
                    record.idempotencyKey
                ) {
                    return@post
                }

                processingInFlight = false

                when (outcome) {
                    ProcessingOutcome.COMPLETED -> {
                        finalizeRecord(
                            record,
                            ParamFetchState.APPLIED
                        )
                    }

                    ProcessingOutcome.REJECTED -> {
                        finalizeRecord(
                            record,
                            ParamFetchState.REJECTED
                        )
                    }

                    ProcessingOutcome.RETRYABLE_FAILURE -> {
                        state =
                            ParamFetchState.RETRYABLE_FAILURE
                    }
                }
            }
        }
    }

    private fun finalizeRecord(
        record: PendingAttributionRecord,
        terminalState: ParamFetchState
    ) {
        val store = HostAppDependencies.transactionStore
            ?: run {
                state = ParamFetchState.RETRYABLE_FAILURE
                return
            }

        if (activeRecord?.idempotencyKey !=
            record.idempotencyKey
        ) {
            return
        }

        // この例では、永続的な最終ジャーナリングとアトミックなクリーンアップをホストストアに委任します。
        // clear()はクリーンアップが成功したかどうかを報告する必要がある。
        val cleared = try {
            store.clear()
        } catch (_: Exception) {
            false
        }

        if (!cleared) {
            state = ParamFetchState.RETRYABLE_FAILURE
            return
        }

        activeRecord = null
        state = terminalState

        Log.i(
            "OpoInstall",
            "インストールパラメータの処理が解決しました"
        )
    }
}

Androidサンプルには、PendingTransactionStoreのデフォルト実装や、成功を自動的に報告するテレメトリクライアントは含まれていません。

ワークフローを呼び出す前に、ホストアプリがこれらを提供する必要があります。

特に、プロセッサはログ出力や非同期リクエストの開始のみをもってCOMPLETEDを返してはなりません。完了した結果は、実際のペイロードに対する処理要件と一致している必要があります：

• UTMのみのペイロード: 必要なアトリビューションイベントが、構成された分析システムまたは永続的なイベントキューに確実に受け入れられている。
• 報酬のみのペイロード: 認証済みバックエンドが承認済みの最終結果を返している。
• UTMと報酬の混合ペイロード: 両方のチャネルが独立して定義された成果に到達しており、片方のチャネルが他方に必要な作業を時期尚早に削除しない。

ホストアプリがプロセスをまたいだ復元を必要とする場合、プロセッサと保護されたストアは、チャネル固有の進行状況を十分に永続化し、安定したトランザクション識別子を保持しなければなりません。

上記のアクティビティは統合の境界を示しており、アプリ固有の実装の代わりとなるものではありません。

iOSネイティブ実装：SDK復元とアプリ統合契約

iOSの統合も同様の境界に従います。

ネイティブSDKが候補となるインストールパラメータを提供し、アプリがペイロードを検証し、ホスト提供のストレージコンポーネントを介して保留レコードを永続化し、ビジネス処理をアプリ所有のコーディネーターに委任します。

このコードは代表的な例であり、インストールされているOpoInstall iOS SDKリリースのモジュール名、デリゲートプロトコル、コールバック署名に合わせて調整する必要があります。

// CODE_BLOCK_03: 代表的なiOS統合 (Swift)
// ファイル: AppDelegate.swift
//
// 展開されたOpoInstallフレームワークバージョンに対してモジュールとSDKメソッドを確認してください。

import UIKit
import libOpoInstallSDK

enum ParamFetchState: String {
    case notStarted = "NOT_STARTED"
    case fetching = "FETCHING"
    case received = "RECEIVED"
    case applied = "APPLIED"
    case rejected = "REJECTED"
    case noMatch = "NO_MATCH"
    case retryableFailure = "RETRYABLE_FAILURE"
}

struct PendingAttributionRecord: Codable {
    let utmSource: String?
    let utmMedium: String?
    let utmCampaign: String?
    let inviterId: String?
    let promoCode: String?
    let idempotencyKey: String
    let createdAt: TimeInterval
    let expiresAt: TimeInterval

    var hasAttributionData: Bool {
        return [
            utmSource, utmMedium, utmCampaign
        ].contains { !$0.isNilOrEmpty }
    }

    var hasRewardData: Bool {
        return !inviterId.isNilOrEmpty ||
               !promoCode.isNilOrEmpty
    }

    var hasAnyData: Bool {
        return hasAttributionData || hasRewardData
    }

    var isValid: Bool {
        let now = Date().timeIntervalSince1970
        let window = expiresAt - createdAt

        let pattern = "^[A-Za-z0-9_.-]{1,64}$"

        let fields = [
            utmSource, utmMedium, utmCampaign,
            inviterId, promoCode
        ]

        let validFields = fields.allSatisfy { field in
            guard let field = field else { return true }
            return field.range(
                of: pattern,
                options: .regularExpression
            ) != nil
        }

        return hasAnyData &&
               validFields &&
               UUID(uuidString: idempotencyKey) != nil &&
               window > 0 &&
               window <= 48 * 60 * 60 &&
               now >= createdAt &&
               now <= expiresAt
    }
}

private extension Optional where Wrapped == String {
    var isNilOrEmpty: Bool {
        return self?.isEmpty ?? true
    }
}

// ホスト提供の保護された永続化契約
protocol PendingTransactionStore {
    func save(_ record: PendingAttributionRecord) -> Bool
    func load() throws -> PendingAttributionRecord?
    func clear() -> Bool
}

enum ProcessingOutcome {
    case completed
    case rejected
    case retryableFailure
}

// 分析および報酬処理のためのホスト提供コーディネーター
protocol InstallParameterProcessor {
    func process(
        record: PendingAttributionRecord,
        completion: @escaping (ProcessingOutcome) -> Void
    )
}

// これらはアプリの契約であり、OpoInstall APIではない。
struct HostAppDependencies {
    static var transactionStore: PendingTransactionStore?
    static var parameterProcessor: InstallParameterProcessor?

    static var isConfigured: Bool {
        return transactionStore != nil &&
               parameterProcessor != nil
    }
}

@UIApplicationMain
class AppDelegate:
    UIResponder,
    UIApplicationDelegate,
    OpoInstallDelegate {

    var window: UIWindow?

    private var state: ParamFetchState = .notStarted
    private var activeRecord: PendingAttributionRecord?
    private var processingInFlight = false

    private let transactionTTL: TimeInterval =
        24 * 60 * 60

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:
            [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        // 代表的なSDK初期化
        OpoInstallSDK.initWith(self)

        // ホストアプリは、パラメータ処理を開始する前に
        // 実際の依存関係を登録する必要がある。
        //
        // HostAppDependencies.transactionStore =
        //     hostProvidedProtectedStore
        //
        // HostAppDependencies.parameterProcessor =
        //     hostProvidedInstallParameterProcessor

        startParameterFlow()
        return true
    }

    private func startParameterFlow() {
        guard HostAppDependencies.isConfigured,
              let store = HostAppDependencies.transactionStore
        else {
            print(
                "OpoInstall: 必要なホストの依存関係が利用できません"
            )
            state = .retryableFailure
            return
        }

        do {
            if let saved = try store.load() {
                if saved.isValid {
                    activeRecord = saved
                    state = .received
                    processRecord(saved)
                    return
                }

                guard store.clear() else {
                    state = .retryableFailure
                    return
                }
            }
        } catch {
            // 読み込みエラーはストアが空であることとは同等ではない
            state = .retryableFailure
            return
        }

        requestInstallParameters()
    }

    private func requestInstallParameters() {
        guard HostAppDependencies.isConfigured,
              state != .fetching,
              state != .applied,
              state != .noMatch,
              !processingInFlight
        else {
            return
        }

        guard let manager = OpoInstallSDK.defaultManager()
        else {
            state = .retryableFailure
            return
        }

        state = .fetching

        // 代表的なコールバック署名
        manager.getInstallParmsCompleted({
            [weak self] (appData: OpoinstallData?) in

            DispatchQueue.main.async {
                guard let self = self,
                      self.state == .fetching
                else {
                    return
                }

                let rawData: Any? = appData?.data

                guard let record =
                    self.parseAndSanitizeRawPayload(rawData)
                else {
                    // 対象のカスタムパラメータが復元されなかった
                    // これはオーガニックトラフィックの決定的な証拠ではない
                    self.state = .noMatch
                    return
                }

                guard HostAppDependencies.isConfigured,
                      let store =
                          HostAppDependencies.transactionStore
                else {
                    self.state = .retryableFailure
                    return
                }

                self.activeRecord = record

                guard store.save(record) else {
                    // 永続化に失敗したときは、確実な保留レコードを
                    // 主張してはならない。
                    self.state = .retryableFailure
                    return
                }

                self.state = .received
                self.processRecord(record)
            }
        })
    }

    private func parseAndSanitizeRawPayload(
        _ rawData: Any?
    ) -> PendingAttributionRecord? {

        guard let rawData = rawData else {
            return nil
        }

        var dictionary: [String: Any]?

        if let map = rawData as? [String: Any] {
            dictionary = map
        } else if let jsonString = rawData as? String,
                  jsonString.count <= 4096,
                  let data = jsonString.data(using: .utf8),
                  let parsed = try? JSONSerialization.jsonObject(
                      with: data
                  ) as? [String: Any] {
            dictionary = parsed
        }

        guard let payload = dictionary else {
            return nil
        }

        let pattern = "^[A-Za-z0-9_.-]{1,64}$"

        func field(_ key: String) -> String? {
            guard let value = payload[key] as? String,
                  value.range(
                    of: pattern,
                    options: .regularExpression
                  ) != nil
            else {
                return nil
            }

            return value
        }

        let now = Date().timeIntervalSince1970

        let record = PendingAttributionRecord(
            utmSource: field("utm_source"),
            utmMedium: field("utm_medium"),
            utmCampaign: field("utm_campaign"),
            inviterId: field("inviter_id"),
            promoCode: field("promo_code"),
            idempotencyKey: UUID().uuidString,
            createdAt: now,
            expiresAt: now + transactionTTL
        )

        return record.isValid ? record : nil
    }

    private func processRecord(
        _ record: PendingAttributionRecord
    ) {
        guard record.isValid,
              let processor =
                  HostAppDependencies.parameterProcessor
        else {
            state = .retryableFailure
            return
        }

        guard !processingInFlight else {
            return
        }

        processingInFlight = true

        // ホストプロセッサは必要なアトリビューションと
        // 報酬の成果を個別に確認しなければならない。
        processor.process(record: record) {
            [weak self] outcome in

            DispatchQueue.main.async {
                guard let self = self,
                      self.activeRecord?.idempotencyKey ==
                          record.idempotencyKey
                else {
                    return
                }

                self.processingInFlight = false

                switch outcome {
                case .completed:
                    self.finalizeRecord(
                        record,
                        terminalState: .applied
                    )

                case .rejected:
                    self.finalizeRecord(
                        record,
                        terminalState: .rejected
                    )

                case .retryableFailure:
                    self.state = .retryableFailure
                }
            }
        }
    }

    private func finalizeRecord(
        _ record: PendingAttributionRecord,
        terminalState: ParamFetchState
    ) {
        guard activeRecord?.idempotencyKey ==
                  record.idempotencyKey,
              let store =
                  HostAppDependencies.transactionStore
        else {
            state = .retryableFailure
            return
        }

        // ホストストアは、アプリの信頼性ニーズに合わせて
        // 永続的な完了とクリーンアップを調整する必要がある。
        guard store.clear() else {
            state = .retryableFailure
            return
        }

        activeRecord = nil
        state = terminalState

        print(
            "OpoInstall: インストールパラメータの処理が解決しました"
        )
    }
}

iOSの例には、UserDefaultsベースの保留中トランザクションストアや、自動的に成功を報告するテレメトリクライアントは含まれていません。

ホストアプリは、自身のセキュリティ、分析、アカウント管理要件に適したストレージ実装とパラメータプロセッサを提供する必要があります。

アプリが報酬を伴う値を処理する場合、プロセッサはサーバーサイドの承認が終了する前に.completedを返してはなりません。

ペイロードがマーケティングデータのみを含む場合、完了報告はアプリで定義された分析の受け入れや、信頼性の高いキューイング要件を反映する必要があります。

混合レコードの場合、プロセッサは各チャネルで未解決の作業を保持し、古いコールバックが別のトランザクションを誤って完了させないようにする必要があります。

代表的なコードは、完全なリトライスケジューラや永続的なマルチチャネルのトランザクションジャーナルを意図的に省略しています。それらの懸念はホストアプリの実装に属するものであり、実際のライフサイクルやバックエンドに対してテストされなければなりません。

本番統合の境界と検証チェックリスト

モバイル側の例をデプロイする前に、エンジニアリングチームは以下の条件を確認してください。

これらは統合の受け入れ基準であり、リファレンスコードや特定のSDKリリースが既に本番試験に合格しているという主張ではありません。

パラメータ引き継ぎ戦略比較行列

パラメータ復元戦略の定量的分析

モバイル獲得システムでは、Web訪問とネイティブアプリ間で参照元やアトリビューションコンテキストを保持するために、異なるアプローチを使用します。

適切なアプローチは、ターゲットプラットフォーム、必要なパラメータ型、許容可能なユーザー摩擦、データの機密性、利用可能なプラットフォームメカニズムに依存します。

精度、プライバシーコンプライアンス、ユーザー摩擦、セキュリティ境界の評価

手動プロモーションコード入力は技術的に推論しやすいが、ユーザーの摩擦を生む可能性がある。

Google Play Install Referrerは、ストアがサポートするAndroid公式の参照チャネルを提供する。

サードパーティのパラメータ復元SDKは、対象となる遅延コンテキストのためのアプリレベルの統合層を提供できる。ただし、その実際のカバー範囲、技術的メカニズム、プライバシー特性は、必ず展開されたリリースを用いて評価しなければならない。

復元方法に関係なく、アプリは「パラメータの受信」と「ビジネスアクションの承認」を明確に区別する必要がある。

パラメータ復元、状態管理、SDK統合エラーのトラブルシューティング

クライアントサイドの状態遷移管理：No-Match、リトライ、最終成果の取り扱い

パラメータ復元ワークフローは、7つの論理状態で説明できます：

これらの状態はアプリレベルの成果を表しており、ホストアプリの分析、報酬、ストレージ、リトライのための永続的な調整を置き換えるものではありません。

特に、マーケティング専用レコードは報酬承認なしで完了できる一方、報酬を伴うレコードは適切なサーバー応答を得る必要がある。

NO_MATCHの結果を、インストールがオーガニックであった決定的な証拠と見なしてはならない。

パラメータ要求のタイムアウトとネットワーク遅延の適切な処理

パラメータ復元は、接続性、コールバックタイミング、アプリ起動順序、または利用不可能なバックエンドサービスの影響を受ける可能性がある。

アプリは以下を行うべきである：

• ネットワーク作業は非同期に保つ。
• インストールパラメータ取得中、メインUIをブロックしない。
• 利用不可能なSDKマネージャーと、空のパラメータ結果を区別する。
• ローカルの永続化エラーを、レコードが存在しないことの確認ではなく、処理失敗として扱う。
• フォアグラウンド移行のたびに要求を発行し続けるのではなく、境界のあるポリシーに従ってリトライする。
• 操作をリトライする必要がある場合、既存の保留レコードを保持する。

自動的にリトライする実装は、リクエストの重複を防ぎ、取って代わられたトランザクションに属するコールバックを拒否しなければならない。

アプリの更新インストールと古いパラメータバッファの管理

パラメータ復元は通常、インストール後の初回起動をターゲットとするが、アプリのアップグレードや繰り返しの起動は、以前にローカルに保存された状態を露呈する可能性がある。

エンジニアリングチームは、いつ復元を試行するのか、消費済みレコードをどのように識別するのか、保留データがいつ期限切れになるのかを定義すべきである。

報酬を伴うパラメータについては、サーバーサイドの冪等性が不可欠である。クライアント側のフラグ単体では、報酬の二重付与に対する十分な保護にはならない。

アプリが保留トランザクションをローカルで維持する場合、必要な処理結果が永続的に解決された後にのみ、レコードを削除すべきである。

Androidのマルチプロセス再初期化問題の防止

複数のプロセスを持つAndroidアプリは、Application.onCreate()を複数回実行する可能性がある。

ネイティブSDKがメインアプリプロセスでのみ初期化される意図である場合、初期化前に現在のプロセスを確認すべきである。

Androidのサンプルは、一つのプロセス名比較戦略を示している。本番環境のアプリは、サポートしているAndroidバージョンとプロセスアーキテクチャに対して、そのアプローチを確認すべきである。

クライアントコールバック署名の不一致とコード縮小（難読化）ルールのデバッグ

サードパーティSDKのパッケージ名、コールバックインターフェース、クラス宣言は、リリースごとに異なる可能性がある。

統合に失敗した場合、開発者は例のインターフェースが変更されていないと想定せず、実際に展開されているSDKを検証すべきである。

Androidのリリースビルドに対して：

• SDKアーティファクトに付属するコンシューマー用R8 / ProGuardルールを優先する。
• 証拠なしに、広範なパッケージ全体の-keepや-dontwarnルールを避ける。
• 狭い補足ルールを追加する前に、実際のリフレクション要件を調査する。
• 縮小されたリリース設定で、インストールパラメータのコールバックをテストする。

このガイドのコードは代表的な統合例であり、ビルドおよびランタイムの証拠がない限り、リリース検証済みとして記述してはならない。

要約と判断フレームワーク

Webクリックとモバイルアプリストアのインストールを紐付けるには、ブラウザ、アプリストア、ネイティブアプリ間の技術的境界を尊重したパラメータ復元アプローチが必要です。

Androidについては、Google Play Install Referrer APIがサポート対象のインストールフローに対して公式の参照メカニズムを提供します。iOSについては、任意のWebパラメータはApp Storeを通じて自動配信されないため、遅延復元には個別に検証されたプライバシーを意識したアプローチが必要です。

実用的なOpoInstallの統合では、許可リストのランディングページパラメータをキャプチャし、ネイティブSDKを通じて適切なコンテキストを要求できます。その後、アプリ側で復元されたデータを正規化および検証し、マーケティングアトリビューション、ナビゲーション、またはプロモーションワークフローに使用する必要があります。

重要なエンジニアリング上の区別は、パラメータの復元とアプリ側の処理の違いです。パラメータを復元したからといって、分析配信、報酬資格、あるいは承認成功が保証されるわけではありません。

リファレンスコードはSDK統合の境界とアプリ定義の契約を示しています。本番チームは、独自の保護されたストレージ、信頼性の高い分析処理、サーバーサイドの資格検証、およびライフサイクル調整を提供しなければなりません。

ベンダーの統合要件を調べるには、OpoInstall SDKドキュメントまたはOpoInstall開発者登録ページを参照してください。

関連資料

概念: アプリパラメータインストール、Google Play Install Referrer、遅延パラメータ復元、アトリビューションテレメトリ、サーバー承認境界。

技術: Web JS SDK、ネイティブモバイルSDK、URLクエリパラメータ、Android Keystore、iOS Keychain Services。

標準: IETF RFC 3986 URI構文、OWASPモバイルアプリケーションセキュリティ検証標準、W3CクリップボードAPIおよびイベント。

API: OpoInstallネイティブインストールパラメータAPI、Google Play Install Referrer API、Apple UIPasteboard API、AndroidクリップボードAPI。

公式ドキュメントおよび参考文献:

• Apple Developer — ユーザーのプライバシーとデータの使用

• Android Developers — Google Play Install Referrer API

• W3C — クリップボードAPIおよびイベント仕様

• OpoInstall — SDK統合ドキュメント