Webシェアにおけるモバイル紹介トラッキングを自動化する方法

モバイル向けの自動紹介トラッキングを設定するにはどうすればよいですか？自動紹介トラッキングの設定には、アトリビューションSDKの統合、難読化された紹介トークン（shareCode）のWebシェアリンクへの付与、ランディングページでのキャプチャ、およびプラットフォームがサポートする遅延ディープリンクを活用した初回アプリ起動時のパラメータ復元が含まれます。

自動紹介トラッキングとは、既存ユーザーのシェアアクションにモバイルアプリのインストールをプログラムで紐付けるエンジニアリング基盤です。難読化された紹介者識別子（shareCode）をWebランディングページ経由で伝送し、アプリの初回起動時にこのコンテキストの解決を試みることで、自動紹介トラッキングは手動でのプロモーションコード入力を削減し、アプリ内ブラウザコンテナ内でのアトリビューションをサポートします。

アーキテクチャの概要：自動紹介トラッキングがソーシャルシェアをアプリインストールに結びつける仕組み

レガシーな紹介システムの構造的課題：手動プロモーションコードがファネルの速度を低下させる理由

従来のモバイル紹介プログラムは、手動の英数字のプロモーションコードに依存していました。このレガシーなワークフローでは、既存ユーザーが招待コード（INVITE2026など）を生成し、そのテキストを手動でコピーして、SMSやソーシャルメッセージング経由で知人に送信します。招待されたユーザーは、アプリストアからアプリをダウンロードし、登録を完了させ、専用のプロモーションコード入力フィールドを探して、文字列を正確に手入力する必要があります。

この手動プロセスは、コンバージョンファネル全体に大きな摩擦（フリクション）をもたらします。

• 認知的・物理的な離脱: ユーザーはクーポンコードのコピーを忘れがちであり、深いオンボーディングメニューの中からコード入力欄を見つけられなかったり、大文字小文字の誤りや入力ミスでコードが無効になった際にプロセスを放棄したりします。
• チャネルの漏洩とコードのスクレイピング: 英数字のコードは簡単に抽出され、公開されているクーポンのアグリゲーターサイトや掲示板に掲載されてしまいます。これにより本来のピアツーピアの関係性が断たれ、紹介されていないオーガニックユーザーが報酬を受け取れるようになる一方で、キャンペーンの単体経済性が損なわれます。
• 測定のブラインドスポット: 手動のプロモーションコードのみに依存している場合、別個の分析インストルメンテーションが導入されていない限り、中間ファネルの節目（リンクのインプレッション、ソーシャルWebviewのクリック、ストアへの遷移率など）が測定されないままになります。

プログラムによる共有パイプライン：紹介者のアクション、Webステージング、ストアへの引き渡し、およびDay 0の解決

自動紹介トラッキングは、手動でのテキスト入力を、継続的かつプログラムによるパラメータ引き渡しパイプラインに置き換えます。パラメータ化されていないストアリンクを切り離されたテキストバウチャーと一緒に配信するのではなく、アプリケーションは紹介者の身元情報をインタラクティブなWebシェアURLに直接組み込みます。

技術的なライフサイクルは、4つの個別段階で動作します。

[既存ユーザーが友人を知人に招待] ──> shareTelemetry.reportIntent(shareCode, Platform)を呼び出し
              │
              ▼
[動的Webリンクの生成] ───> 宛先URLに ?shareCode=usr_9f82a1b4 を付与
              │
              ▼
[WeChat/LINE内でシェア] ────> 友人がサンドボックス化されたWebview内でリンクをタップ
              │
              ▼
[Web JS SDKのステージングと引き渡し] ─> コンテキストをキャッシュし、アプリ起動/ストアダウンロードを実行
              │
              ▼
[デバイスでの初回アプリ起動] ───> ネイティブSDKがパラメータの復元をクエリ
              │
              ▼
[アプリケーションバックエンドの紐付け] ──> バックエンドがトークンを検証し、保留中の紐付けを作成
              │
              ▼
[検証済みの有効化マイルストーン] ─> マイルストーンの完了時にバックエンドが報酬を給付

招待されたユーザーがリンクを開くと、ホストされているWebランディングページがWeb JS SDKを実行し、紹介者のトークン（shareCode）を抽出して紹介コンテキストをステージングします。ユーザーが続けてネイティブアプリケーションをインストールして起動すると、クライアントSDKが初期起動時にステージングされたペイロードを取得し、双方の参加者による手動データ入力を必要とせずに、アプリケーションバックエンドが紹介関係を自動的に紐付けることを可能にします。

ストアインストール後の初回起動時の復元：プラットフォーム固有の制限

ユーザーがアプリストアからアプリケーションをインストールした後、紹介パラメータの復元は、プラットフォームおよびアプリケーションまたはアトリビューションSDKによって実装されたメカニズムに依存します。Web URL経由でshareCodeを渡すこと自体では、新しくインストールされたアプリケーションでそのパラメータが利用可能になることは保証されません。

Android / Google Play: Google Play Install Referrerは、Playストアのインストールに関連するサポート対象の紹介メタデータを提供できます。アプリケーションは、実際の参照元ペイロードを設定およびテストし、期待されるパラメータがリダイレクトおよびインストールのフローを生き残ることを確認する必要があります。サードパーティのアトリビューションSDKは、別途文書化する必要のある追加のメカニズムを使用する場合があります。
iOS / App Store: App Storeは、任意のランディングページのクエリパラメータをインストールされたアプリケーションに自動的に転送しません。ユニバーサルリンク（Universal Links）は、アプリケーションがすでにインストールされており、関連するドメイン設定が有効な場合に直接ルーティングをサポートしますが、新規インストール後の遅延パラメータ復元をそれ単体で保証するものではありません。
アトリビューションSDK: 展開される正確なSDKバージョンとプラットフォームに対して文書化されている復元メカニズムのみを使用してください。SDKがあらゆるブラウザやインストールパスですべての紹介パラメータを復元できると仮定するのではなく、実装、データ収集、およびプライバシーへの影響を検証してください。

サポートされているメカニズムを通じて紹介コンテキストを復元できない場合は、ユーザーにオンボーディングを完了させ、インストールをアトリビューションなし（unattributed）として記録してください。未検証の一致から紹介関係を推測したり、捏造したりしないでください。

iOSのアトリビューションとプライバシーの境界

iOSの紹介実装では、アプリケーションやWebサイトを跨いでユーザーやデバイスを識別するために、禁止されているデバイスフィンガープリンティングに依存してはなりません。Appleのプライバシーおよびデータ利用要件では、この目的のためにデバイス、ブラウザ、構成、位置情報、またはネットワークシグナルから一意の識別子を導出することを禁止しています。App Tracking Transparency（ATT）の承認により、本来は禁止されているフィンガープリンティングが許可されるわけではありません。

アプリケーションがインストールされている場合は、検証済みの直接アプリルーティングのためにユニバーサルリンクを使用してください。インストール後の紹介復元については、デプロイされたSDKのバージョンおよび適用されるAppleの要件に対して動作がレビューされている、文書化されたメカニズムを使用してください。必要に応じてSDKのプライバシー開示事項や必須理由APIの宣言を確認しますが、プライバシーマニフェストの存在をアトリビューションの実装が準拠していることの証明として扱わないでください。

選択したSDKが許可されていると検証できないマッチング方法に依存している場合、iOSへのデプロイメントにその方法を推奨しないでください。SDKプロバイダーから明確な説明を得て、準拠している代替手段を選択してください。許可されたメカニズムで紹介関係を確実確立できない場合は、通常のオンボーディングフローを維持し、インストールをアトリビューションなしとしてマークしてください。

参考: Appleのユーザープライバシーとデータ利用。

関連記事: 紹介トラッキング ──> アプリパラメータのインストール

ステップ 1：クライアント側のシェア報告APIのインストルメンテーション

AndroidおよびiOSのエントリポイントでのネイティブアトリビューションSDKの初期化

アプリケーションが共有アクティビティを報告したり、着信した紹介コンテキストを取得したりする前に、アプリのライフサイクルの早い段階でネイティブモバイルSDKを初期化する必要があります。

Androidでは、初期化はカスタムのApplicationサブクラスのonCreate()メソッド内で行い、フォアグラウンドのUIコンポーネントがマウントされる前にアトリビューションリスナーとコアメモリ構造が確立されるようにします。iOSでは、初期化はapplication(_:didFinishLaunchingWithOptions:)実行デリゲート内で行われます。

開発者は、OpoInstall SDKダウンロードセンターから公式モバイルSDKパッケージを直接取得できます。

ネイティブOSのシェアシートをトリガーする前のシェア報告メソッドの呼び出し

アプリケーションは、プラットフォームのシェアインターフェースを開く前にシェアの意図を記録する必要があります。これは、アプリケーションが所有するテレメトリサービス、または使用中の正確なSDKバージョンに対して検証されたアトリビューションSDKメソッドを通じて実装します。以下の例では、アプリケーションが所有するshareTelemetry.reportIntent(...)抽象化を使用しており、これは公式のOpoInstall APIではありません。アダプターは、デプロイされたアプリケーション向けに実際のネットワークリクエスト、エラーハンドリング、およびコールバック動作を実装する必要があります。

クリーンなテレメトリを維持するため、エンジニアリングチームは共有ライフサイクルにおける5つの異なるイベントを区別する必要があります。

• シェア意図の開始（share_intent_initiated）: クライアントアプリのUIが、ユーザーが招待アクションをクリックしたことをログに記録します。
• シェアのディスパッチ（share_dispatched）: クライアントアプリがペイロードを指定された宛先プラットフォームに渡す（例：明示的なソーシャルインテントの起動）、またはシステムシェアチューザーを開きます。
• シェアの完了（share_completed）: サードパーティのソーシャルSDKが、メッセージが投稿またはディスパッチされたことを確認する認証済み完了コールバックを返します（コールバックをサポートする専用のサードパーティプラットフォームSDKを使用する場合にのみ適用されます）。
• 紹介のクリック（referral_click）: 受信者がWebランディングページを開き、Web側の流入ログ記録をトリガーします。
• 紹介の紐付け（referral_bound）: 受信者がアカウント登録を完了し、バックエンドが候補のshareCodeを検証してデータベースに紹介関係を書き込みます。

シェアテレメトリを記録することで、共有に対するユーザーの意図を捉えることができます。これにより、分析パイプラインが紹介者のshareCodeを指定されたプラットフォームチャネルと関連付けてインデックス化できるようになり、その後のWebランディングページの訪問を相関させるシステムを準備できます。

プラットフォーム識別子の指定：ソーシャルチャネルのマッピング

以下の識別子はあくまで説明のための例です。デプロイされたSDKバージョンがサポートする正確なチャネル列挙を使用し、各識別子を公式のAPIリファレンスと照らし合わせて検証してください。

• クローズドメッセージングネットワーク: WechatSession（WeChatダイレクトチャット）、WechatTimeline（WeChatモーメンツ）、Line、WhatsApp、FacebookMessenger。
• ソーシャルフィードおよびパブリックマイクロブログ: Twitter、Facebook、Instagram、Weibo、Douyin、TikTok。
• 直接オペレーティングシステムトランスポート: Sms、Email、Copy（クリップボードリンクコピー）、およびOther（システムシェアシート）。

ユーザーの最終的な宛先の選択を事前に決定できない汎用的なシステムシェアシートをアプリケーションが起動する場合、イベントは特定のソーシャルネットワークをハードコーディングするのではなく、Otherとして分類する必要があります。

紹介者識別子トークンの構造化：shareCodeのフォーマットに関するベストプラクティス

shareCodeは、新規インストールを紹介元のアカウントに接続するアプリケーションレベルのビジネストークンとして機能します。開発者は任意の英数字文字列を使用できますが、構造上のベストプラクティスを遵守することでパラメータの破損を防ぎます。

• 難読化されたサーバー発行トークン: shareCodeは、連番の生データベース自動インクリメントID（1024）ではなく、難読化されたサーバー発行の紹介トークン（URLセーフなトークンやusr_9f82a1b4のようなUUIDなど）にする必要があります。アプリケーションのバックエンドはこのトークンを招待者アカウントに解決し、有効期限とレートリミットを適用します。
長さの制限: URLの長さを膨らませたり、メッセージングアプリでの文字列の切り捨てを引き起こしたりしないよう、トークンをコンパクトに保ちます（推奨は64文字未満、厳密には\le 128文字未満）。
• 安全な文字セット: 文字はURLセーフな英数字、ハイフン、およびアンダースコア（[A-Za-z0-9_-]）に制限します。URIの解析を変更する&、=、?、スペースなどの生の区切り文字は避けてください。

Android 11（APIレベル30）以降では、サードパーティのソーシャルパッケージがインストールされているかどうかをクエリするには、Android 11におけるパッケージの可視性に関するGoogle Androidデベロッパーガイドに従って、AndroidManifest.xml内に対応する<queries>要素を宣言する必要があります。以下の実装パターンは、パッケージの可視性を宣言する方法、ブロックしないシェア報告のタイムアウトを処理する方法、ライフサイクル安全な状態リセットを管理する方法、およびクリップボードのフォールバックを備えた明示的なソーシャルインテントをディスパッチする方法を示しています。

<!-- Androidの構成とクライアント側のシェア実装 -->
<!-- パート1: AndroidManifest.xmlのパッケージ可視性とアプリケーション宣言 -->
<!-- ファイル: app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

    <!-- Android 11+ (API 30+)で必要とされる明示的なパッケージ可視性宣言 -->
    <queries>
        <package android:name="com.tencent.mm" />
        <package android:name="jp.naver.line.android" />
    </queries>

    <application
        android:name=".CustomApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.AppCompat.Light.NoActionBar">
        
        <activity
            android:name=".InviteActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

// Androidアプリケーションのライフサイクルエントリ
// パート2: CustomApplication.kt（SDKライフサイクルの初期化）
// ファイル: app/src/main/java/com/example/app/CustomApplication.kt

package com.example.app

import android.app.Application
import com.opoinstall.api.OpoInstall

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // アクティビティがマウントされる前に、メインスレッドでOpoInstallコアクライアントを初期化
        OpoInstall.initialize(this)
    }
}

// Androidシェアアクティビティの実装
// パート3: InviteActivity.kt（アプリケーションテレメトリとクリップボードフォールバック付きのターゲットディスパッチ）
// ファイル: app/src/main/java/com/example/app/InviteActivity.kt

package com.example.app

import android.content.ClipData
import android.content.ClipboardManager
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.net.Uri
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.util.Log
import android.widget.Button
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import java.util.concurrent.atomic.AtomicBoolean

class InviteActivity : AppCompatActivity() {

    companion object {
        private const val TAG = "ReferralShareTracking"
        // アプリケーションが所有するリダイレクトエンドポイントの例。デプロイされたHTTPSルートに置き換えてください
        private const val BASE_INVITE_HOST = "promo.example.com"
        private const val BASE_INVITE_PATH = "invite.html"
        
        // 明示的なインテントルーティングのターゲットプラットフォームパッケージ
        private const val PACKAGE_WECHAT = "com.tencent.mm"
        private const val PACKAGE_LINE = "jp.naver.line.android"
        
        // アプリケーション定義のタイムアウト例。実際のテレメトリサービスに合わせて調整・テストしてください
        private const val SHARE_TIMEOUT_MS = 800L
    }

    // 連続する高速なシェアインテントの呼び出しを防ぐためのデバウンスガード
    private val isSharingInProgress = AtomicBoolean(false)

    // アプリケーションが所有するテレメトリアダプターの抽象化
    private val shareTelemetry = ShareTelemetryService()

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

        val btnShareWeChat = findViewById<Button>(R.id.btn_share_wechat)
        val btnShareLine = findViewById<Button>(R.id.btn_share_line)
        val btnShareGeneric = findViewById<Button>(R.id.btn_share_generic)

        // モックトークンの例：本番環境では、認証済みセッションからサーバー発行トークンを取得してください
        val currentInviterToken = "usr_9f82a1b4"

        btnShareWeChat.setOnClickListener {
            initiateShareFlow(currentInviterToken, "WechatSession", targetPackage = PACKAGE_WECHAT)
        }

        btnShareLine.setOnClickListener {
            initiateShareFlow(currentInviterToken, "Line", targetPackage = PACKAGE_LINE)
        }

        btnShareGeneric.setOnClickListener {
            // セグメント化されていないシステムシェアシート。プラットフォームはOtherとして分類
            initiateShareFlow(currentInviterToken, "Other", targetPackage = null)
        }
    }

    /**
     * 特定のチャネルのテレメトリを報告する前に、ターゲットのソーシャルアプリがインストールされているか検証するヘルパー。
     * Android 11+ (API 30+)ではAndroidManifest.xmlでの<queries>宣言が必要です。
     */
    private fun isAppInstalled(packageName: String?): Boolean {
        if (packageName.isNullOrEmpty()) return false
        return try {
            packageManager.getPackageInfo(packageName, PackageManager.GET_ACTIVITIES)
            true
        } catch (e: PackageManager.NameNotFoundException) {
            false
        } catch (e: Exception) {
            Log.w(TAG, "$packageName のパッケージ検査例外: ${e.message}")
            false
        }
    }

    /**
     * 最終的なフォールバックとして、完全な招待URLをシステムのクリップボードにコピーします。
     */
    private fun copyInviteLinkToClipboard(shareUri: String): Boolean {
        return try {
            val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
            clipboard.setPrimaryClip(ClipData.newPlainText("紹介招待リンク", shareUri))
            true
        } catch (e: Exception) {
            Log.e(TAG, "招待リンクのコピーに失敗しました: ${e.message}", e)
            false
        }
    }

    private fun showShareFailureFallback(shareUri: String) {
        val copied = copyInviteLinkToClipboard(shareUri)
        val message = if (copied) {
            "共有アプリを開けません。招待リンクをクリップボードにコピーしました。"
        } else {
            "共有アプリを開くことも、招待リンクをコピーすることもできません。"
        }
        Toast.makeText(this, message, Toast.LENGTH_LONG).show()
    }

    /**
     * ブロックしないタイムアウトフォールバックを使用して、アプリケーションが所有するテレメトリ経由でシェア意図を記録します。
     *
     * @param shareCode 難読化された紹介者トークン（厳密に128文字以下）
     * @param platformIdentifier 報告分類に一致するターゲットソーシャルチャネル
     * @param targetPackage 特定のアプリケーションパッケージ名、または汎用システムチューザーの場合はnull
     */
    private fun initiateShareFlow(shareCode: String, platformIdentifier: String, targetPackage: String?) {
        // デバウンスチェックの適用
        if (!isSharingInProgress.compareAndSet(false, true)) {
            Log.d(TAG, "シェアの呼び出しが既に進行中です。重複したクリックを無視します。")
            return
        }

        val isTargetInstalled = isAppInstalled(targetPackage)
        val effectivePlatform = if (isTargetInstalled) platformIdentifier else "Other"
        val effectivePackage = if (isTargetInstalled) targetPackage else null

        val isDispatched = AtomicBoolean(false)
        val mainHandler = Handler(Looper.getMainLooper())

        // ブロックしないタイムアウト用runnable：ネットワークハンドシェイクが遅延した場合でもUIシェアシートが開くことを保証
        val timeoutRunnable = Runnable {
            if (isDispatched.compareAndSet(false, true)) {
                Log.w(TAG, "${SHARE_TIMEOUT_MS}ms後に事前シェア報告がタイムアウトしました。ディスパッチを続行します。")
                dispatchShareSafely(shareCode, effectivePlatform, effectivePackage)
            }
        }
        mainHandler.postDelayed(timeoutRunnable, SHARE_TIMEOUT_MS)

        // アプリケーションが所有するテレメトリアダプターを介して非同期でシェア意図を報告
        shareTelemetry.reportIntent(shareCode, effectivePlatform) { result ->
            mainHandler.removeCallbacks(timeoutRunnable)
            if (isDispatched.compareAndSet(false, true)) {
                if (result.isFailure) {
                    Log.w(TAG, "シェアテレメトリに失敗しました: ${result.exceptionOrNull()?.message}")
                } else {
                    Log.d(TAG, "$effectivePlatform のシェア意図が記録されました")
                }
                mainHandler.post {
                    dispatchShareSafely(shareCode, effectivePlatform, effectivePackage)
                }
            }
        }
    }

    /**
     * ライフサイクルチェックとfinallyブロックでの確実な状態リセットを行ってインテントディスパッチを実行します。
     */
    private fun dispatchShareSafely(shareCode: String, platform: String, targetPackage: String?) {
        try {
            if (isFinishing || isDestroyed) {
                Log.d(TAG, "アクティビティが終了または破棄されています。シェアディスパッチをスキップします。")
                return
            }
            dispatchShareAction(shareCode, platform, targetPackage)
        } catch (e: Exception) {
            Log.e(TAG, "シェアディスパッチで未処理の例外が発生しました: ${e.message}", e)
        } finally {
            isSharingInProgress.set(false)
        }
    }

    private fun dispatchShareAction(shareCode: String, platform: String, targetPackage: String?) {
        // Uri.Builderを使用してRFC 3986エンコーディングを強制し、宛先URLを安全に構築
        val shareUri = Uri.Builder()
            .scheme("https")
            .authority(BASE_INVITE_HOST)
            .appendEncodedPath(BASE_INVITE_PATH)
            .appendQueryParameter("shareCode", shareCode)
            .appendQueryParameter("platform", platform)
            .build()
            .toString()

        val shareMessage = "アプリに参加してウェルカムクーポンを手に入れよう！ダウンロードはこちら: $shareUri"

        val sendIntent = Intent(Intent.ACTION_SEND).apply {
            putExtra(Intent.EXTRA_TEXT, shareMessage)
            type = "text/plain"
        }

        if (targetPackage != null) {
            sendIntent.setPackage(targetPackage)
            try {
                startActivity(sendIntent)
                return
            } catch (e: Exception) {
                Log.w(TAG, "ターゲットアプリの起動に失敗しました: ${e.message}", e)
            }
        }

        // ターゲットアプリが利用できない場合、またはターゲットシェアの起動に失敗した場合はシステムシェアチューザーを使用
        try {
            sendIntent.setPackage(null)
            val fallbackChooser = Intent.createChooser(sendIntent, "友達を招待する:")
            startActivity(fallbackChooser)
        } catch (e: Exception) {
            Log.e(TAG, "システムシェアチューザーに失敗しました: ${e.message}", e)
            showShareFailureFallback(shareUri)
        }
    }
}

// アプリケーションが所有するテレメトリサービスのインターフェース例
class ShareTelemetryService {
    fun reportIntent(shareCode: String, platform: String, callback: (Result<Unit>) -> Unit) {
        // 実装：アプリケーションのテレメトリバックエンドへのネットワークリクエストのディスパッチ
        callback(Result.success(Unit))
    }
}

アプリケーションプロファイルを登録し、シェアトラッキングに必要な構成キーを取得するには、チームはOpoInstall開発者コンソールにアクセスできます。

ステップ 2：動的シェアパラメータをキャプチャするためのWeb JS SDKの構成

バージョン検証済みアダプターを通じたWeb SDKの統合

以下のランディングページの実装は説明のための統合パターンであり、検証済みのドロップイン形式のOpoInstall SDK統合ではありません。デプロイ前に、正確なJavaScriptバンドルURL、初期化署名、準備完了コールバック、起動またはインストールメソッド、およびパラメータスキーマを、デプロイされるSDKの公式ドキュメントと照らし合わせて確認してください。

SDK固有の動作は、小規模なアプリケーションアダプターの背後に隠蔽してください。アダプターは、文書化された初期化結果と、単一の起動またはインストール操作をランディングページに公開する必要があります。対応するメソッド名、コールバックの動作、および構成要件を検証した後にのみ、これらの操作を実際のベンダーAPIにマッピングしてください。

ランディングページは、引き続き着信したshareCodeを検証し、承認されたフォールバックルート上の紹介パラメータを保持し、重複したナビゲーションを防ぐ必要があります。SDKの初期化に失敗した場合や、文書化されたエントリポイントが利用できない場合は、構成されたフォールバックルートを使用してください。バックエンドとプラットフォームの統合がそれをサポートするようテストされていない限り、フォールバックが遅延アトリビューションを復元できると主張しないでください。

ブラウザのURLSearchParamsによるshareCodeクエリ文字列抽出の自動化

シェアURLが構築されるとき、アプリケーションは紹介者のトークンをクエリパラメータとして追加します（例：https://promo.example.com/invite.html?shareCode=usr_9f82a1b4&platform=WechatSession）。

ランディングページでは、クライアント側のスクリプトがURLSearchParamsなどの標準的なブラウザインターフェースを使用してこの値を取り出します。不正な入力やクロスサイトスクリプティング（XSS）から防御するため、スクリプトはSDKを初期化する前に、許可リスト（ホワイトリスト）およびフォーマットパターンに対してトークンを検証する必要があります。

const query = new URLSearchParams(window.location.search);
const rawShareCode = query.get("shareCode");
const safePattern = /^[A-Za-z0-9_-]{1,128}$/;
const sanitizedShareCode = (rawShareCode && safePattern.test(rawShareCode)) ? rawShareCode : "";

一時メモリおよびシステムバッファへの紹介コンテキストのステージング

Web JS SDKが初期化されると、サニタイズされたshareCodeが追加のキャンペーン識別子（channelCode）とともに取り込まれます。ユーザーがプライマリのコールトゥアクション（CTA）ボタンをタップすると、SDKがコンテキストのステージングを調整します。

• アトリビューションサーバー登録: スクリプトは、現在のWebセッションとクライアントコンテキストをshareCodeにリンクする非同期ネットワークリクエストを送信します。
• システムペーストボードのステージング: クリップボードへのアクセスは、ブラウザの権限、ユーザーのアクティベーション要件、および実装固有のセキュリティポリシーの対象となります。Web実装では、クリップボードのステージングをオプショナルな機能として扱い、アクセスが拒否されたり利用できない場合はフォールバックを提供する必要があります。
• フォールバックの調整: ペーストボードへのアクセスが制限されている、ユーザープロンプトによって拒否された、または後続のユーザーアクションによってクリアされた場合、アトリビューションアーキテクチャはサーバー側のセッションマッチング、またはプラットフォームがサポートするインストール参照元チャネルにフォールバックします。

遅延パラメータ登録を実行するためのダウンロードCTAボタンの紐付け

ランディングページは、プライマリのダウンロードボタンをSDKの実行メソッド（wakeupOrInstall()）に直接紐付けます。

Web JS SDKはリダイレクトライフサイクルを内部的に管理します。構成されたスキーマまたはユニバーサルリンクを介してアプリの起動試行を開始し、アプリがインストールされていない場合は、構成されたアプリストアへの遅延リダイレクトを実行します。ユーザーランドのコードは、通常実行時にはSDKの内部ナビゲーション管理に依存し、SDKスクリプトのロードに失敗した場合や同期例外をスローした場合、またはブラウザのセキュリティコントロールによってブロックされたシナリオのために、直接のフォールバックナビゲーションを確保する必要があります。

以下の実装パターンは、着信したshareCodeクエリパラメータのキャプチャ、アプリ内ソーシャルコンテナの検出、クリックキュー状態の管理、および重複キーや不正なURIフラグメントなしでのフォールバックルート全体のパラメータ保持を行うために、Web JS SDKを統合する方法を示しています。

<!-- Web JS SDK動的シェアパラメータの取り込みとルーティング -->
<!-- ファイル: /var/www/html/invite.html -->
<!--
統合に関する注意:
この例では、デプロイされたSDKバージョンに対して検証されたアダプターが必要です。
説明用のスニペットに示されているコンストラクター、CDNパス、コールバック、
またはメソッド名が現在のベンダーSDKと一致していると仮定しないでください。
-->
<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>紹介招待を受け入れる</title>
    <!-- 公式CDNから検証済みのOpoInstall Web JS SDKをインクルード -->
    <script src="https://web.cdn.opoinstallcloud.com/opoinstall.js"></script>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            margin: 0;
            padding: 20px;
            text-align: center;
            background-color: #f8fafc;
        }
        .card {
            background: #ffffff;
            border-radius: 12px;
            padding: 32px 24px;
            max-width: 420px;
            margin: 40px auto;
            box-shadow: 0 4px 6px -1px rgba(0,0,0,0.1);
        }
        button {
            background-color: #2563eb;
            color: #ffffff;
            border: none;
            padding: 14px 28px;
            font-size: 16px;
            font-weight: 600;
            border-radius: 8px;
            cursor: pointer;
            width: 100%;
            margin-top: 20px;
        }
        button:disabled {
            background-color: #94a3b8;
            cursor: not-allowed;
        }
        /* 制限されたアプリ内webviewコンテナ向けの視覚的ガイダンスオーバーレイ */
        .webview-guide-mask {
            display: none;
            position: fixed;
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            background: rgba(0, 0, 0, 0.85);
            color: #ffffff;
            z-index: 9999;
            padding-top: 40px;
            box-sizing: border-box;
        }
        .guide-arrow {
            font-size: 32px;
            text-align: right;
            padding-right: 30px;
        }
        .guide-text {
            font-size: 18px;
            line-height: 1.6;
            margin-top: 20px;
            padding: 0 30px;
        }
    </style>
</head>
<body>
    <main class="card">
        <h1>アプリへようこそ</h1>
        <p id="invite-desc">友達から招待が届いています。下をタップしてインストールし、ウェルカム特典を受け取りましょう。</p>
        
        <!-- プライマリコンバージョンボタン -->
        <button id="btn-install" type="button">ダウンロードして特典を獲得</button>
        
        <!-- アプリケーションが所有するリダイレクトエンドポイントの例。デプロイされたHTTPSルートに置き換えてください -->
        <p style="margin-top: 16px; font-size: 14px;">
            <a id="fallback-store-link" href="https://promo.example.com/app-redirect">ダイレクトストアリンク</a>
        </p>
    </main>

    <!-- 制限されたメッセージングwebview（WeChat、LINE）内に表示されるオーバーレイプロンプト -->
    <div id="webview-guide" class="webview-guide-mask">
        <div class="guide-arrow">↗</div>
        <div class="guide-text">
            右上隅のメニュー（•••）をタップし、<strong>「ブラウザで開く」</strong>（Safari / Chrome）を選択してアプリをダウンロードしてください。
        </div>
    </div>

    <script>
    /**
     * window.locationからshareCodeクエリパラメータを抽出してサニタイズします。
     * 仕様に従い、最大128文字までのURLセーフな英数字の範囲を強制します。
     */
    function getSanitizedShareCode() {
        try {
            const query = new URLSearchParams(window.location.search);
            const rawCode = query.get("shareCode");
            const pattern = /^[A-Za-z0-9_-]{1,128}$/;
            return (rawCode && pattern.test(rawCode)) ? rawCode : "";
        } catch (e) {
            console.error("検索パラメータの解析に失敗しました:", e);
            return "";
        }
    }

    /**
     * platformクエリパラメータを抽出してサニタイズします。
     */
    function getSanitizedPlatform() {
        try {
            const query = new URLSearchParams(window.location.search);
            const rawPlatform = query.get("platform");
            const pattern = /^[A-Za-z0-9_]{1,32}$/;
            return (rawPlatform && pattern.test(rawPlatform)) ? rawPlatform : "";
        } catch (e) {
            return "";
        }
    }

    /**
     * 制限されたアプリ内ブラウザコンテナ（WeChat、LINE、WhatsApp、Facebook）を検出します。
     */
    function detectInAppBrowser() {
        const ua = navigator.userAgent.toLowerCase();
        return {
            isWeChat: ua.indexOf("micromessenger") !== -1,
            isLine: ua.indexOf("line/") !== -1,
            isWhatsApp: ua.indexOf("whatsapp") !== -1,
            isFacebook: ua.indexOf("fbav") !== -1 || ua.indexOf("instagram") !== -1
        };
    }

    /**
     * URIコンポーネントを安全にデコードし、不正なパーセントエンコーディングの場合は生の文字列にフォールバックします。
     */
    function safeDecode(str) {
        if (!str) return "";
        try {
            return decodeURIComponent(str.replace(/\+/g, " "));
        } catch (e) {
            return str;
        }
    }

    /**
     * フォールバックナビゲーションを実行し、URLフラグメントを破損させることなく、
     * URL解析および文字列フォールバックパス全体でshareCodeパラメータを置換または更新します。
     */
    function executeFallbackNavigation(fallbackLink, shareCode, platform) {
        if (!fallbackLink || !fallbackLink.href) {
            console.error("フォールバック先のリンクが定義されていません。");
            return;
        }

        let destinationUrl = fallbackLink.href;
        try {
            const url = new URL(destinationUrl, window.location.origin);
            if (shareCode) {
                url.searchParams.set("shareCode", shareCode);
            }
            if (platform) {
                url.searchParams.set("platform", platform);
            }
            destinationUrl = url.toString();
        } catch (err) {
            console.warn("URL APIの解析に失敗しました。堅牢な文字列フォールバックを適用します:", err);
            const hashIndex = destinationUrl.indexOf("#");
            const fragment = hashIndex !== -1 ? destinationUrl.substring(hashIndex) : "";
            const rawBase = hashIndex !== -1 ? destinationUrl.substring(0, hashIndex) : destinationUrl;

            const qIndex = rawBase.indexOf("?");
            const pathname = qIndex !== -1 ? rawBase.substring(0, qIndex) : rawBase;
            const queryString = qIndex !== -1 ? rawBase.substring(qIndex + 1) : "";

            const params = {};
            if (queryString) {
                const pairs = queryString.split("&");
                for (let i = 0; i < pairs.length; i++) {
                    if (!pairs[i]) continue;
                    const parts = pairs[i].split("=");
                    const key = safeDecode(parts[0]);
                    const value = parts.length > 1 ? safeDecode(parts.slice(1).join("=")) : "";
                    if (key) {
                        params[key] = value;
                    }
                }
            }

            if (shareCode) params["shareCode"] = shareCode;
            if (platform) params["platform"] = platform;

            const serializedPairs = [];
            for (const k in params) {
                if (Object.prototype.hasOwnProperty.call(params, k)) {
                    serializedPairs.push(encodeURIComponent(k) + "=" + encodeURIComponent(params[k]));
                }
            }

            const newQuery = serializedPairs.length > 0 ? "?" + serializedPairs.join("&") : "";
            destinationUrl = pathname + newQuery + fragment;
        }

        window.location.href = destinationUrl;
    }

    document.addEventListener("DOMContentLoaded", function() {
        const shareCode = getSanitizedShareCode();
        const platform = getSanitizedPlatform();
        const inApp = detectInAppBrowser();
        const installBtn = document.getElementById("btn-install");
        const guideOverlay = document.getElementById("webview-guide");
        const fallbackLink = document.getElementById("fallback-store-link");

        // ダウンロードを傍受する制限されたコンテナ内で開かれた場合、視覚的ガイダンスマスクを表示する
        if (inApp.isWeChat || inApp.isLine) {
            if (guideOverlay) guideOverlay.style.display = "block";
        }

        // DOMロード時に静的フォールバックリンクのhrefを直ちに更新し、直接タップでパラメータが保持されるようにする
        if (fallbackLink && fallbackLink.href) {
            try {
                const initialUrl = new URL(fallbackLink.href, window.location.origin);
                if (shareCode) initialUrl.searchParams.set("shareCode", shareCode);
                if (platform) initialUrl.searchParams.set("platform", platform);
                fallbackLink.href = initialUrl.toString();
            } catch (e) {
                // フォールバック解析はクリック時に処理される
            }
        }

        // OpoInstall取り込み用に動的パラメータをパッケージ化する
        const dynamicData = {
            shareCode: shareCode,
            platform: platform
        };

        // SDKの準備状況と1回限りのアクション状態
        let isSdkReady = false;
        let isSdkBlocked = false;
        let isClickQueued = false;
        let actionStarted = false;
        let installerInstance = null;
        let clickTimeoutId = null;

        // アプリケーション定義の初期化フォールバック閾値であり、検証済みのベンダーデフォルトではない
        const SDK_CLICK_TIMEOUT_MS = 1500;

        function clearClickTimeout() {
            if (clickTimeoutId !== null) {
                clearTimeout(clickTimeoutId);
                clickTimeoutId = null;
            }
        }

        function restoreInstallButton() {
            if (!installBtn) return;
            installBtn.disabled = false;
            installBtn.textContent = "ダウンロードして特典を獲得";
        }

        function triggerSdkWakeup() {
            try {
                if (installerInstance && typeof installerInstance.wakeupOrInstall === "function") {
                    installerInstance.wakeupOrInstall({
                        data: dynamicData,
                        channelCode: "viral_social_share"
                    });
                } else {
                    executeFallbackNavigation(fallbackLink, shareCode, platform);
                }
            } catch (err) {
                console.error("SDKの起動に失敗しました:", err);
                executeFallbackNavigation(fallbackLink, shareCode, platform);
            }
        }

        // すべてのナビゲーションパスはこの1回限りのガードを通過する必要がある
        function runOnce(action) {
            if (actionStarted) return;
            actionStarted = true;
            isClickQueued = false;
            clearClickTimeout();

            if (installBtn) {
                installBtn.disabled = true;
                installBtn.textContent = "開いています...";
            }

            action();
        }

        function handleInstallClick() {
            if (actionStarted) return;

            if (isSdkReady) {
                runOnce(triggerSdkWakeup);
                return;
            }

            if (isSdkBlocked) {
                runOnce(function() {
                    executeFallbackNavigation(fallbackLink, shareCode, platform);
                });
                return;
            }

            // SDKの初期化中にクリックをキューに入れる
            isClickQueued = true;
            if (installBtn) {
                installBtn.disabled = true;
                installBtn.textContent = "アプリストアに接続中...";
            }

            clearClickTimeout();

            clickTimeoutId = setTimeout(function() {
                if (actionStarted || isSdkReady || !isClickQueued) {
                    return;
                }
                isSdkBlocked = true;
                runOnce(function() {
                    executeFallbackNavigation(fallbackLink, shareCode, platform);
                });
            }, SDK_CLICK_TIMEOUT_MS);
        }

        if (installBtn) {
            installBtn.addEventListener("click", handleInstallClick);
        }

        // Web JS SDKを初期化する
        if (typeof OpoInstall === "function") {
            try {
                // 構成されたベンダーコンソールから取得したアプリケーションキーに置き換えてください。
                // 本番のシークレットを公開ソース管理にコミットしないでください。
                installerInstance = new OpoInstall({
                    appKey: "OPOINSTALL_APPKEY_PLACEHOLDER",
                    onready: function() {
                        if (this && typeof this.wakeupOrInstall === "function") {
                            installerInstance = this;
                        }

                        isSdkReady = true;
                        clearClickTimeout();

                        // 遅れて届いたコールバックが完了したアクションを繰り返してはならない
                        if (actionStarted) return;

                        if (isClickQueued) {
                            runOnce(triggerSdkWakeup);
                        } else {
                            restoreInstallButton();
                        }
                    }
                });
            } catch (err) {
                console.error("OpoInstallの初期化に失敗しました:", err);
                isSdkBlocked = true;
                clearClickTimeout();

                if (isClickQueued) {
                    runOnce(function() {
                        executeFallbackNavigation(fallbackLink, shareCode, platform);
                    });
                } else {
                    restoreInstallButton();
                }
            }
        } else {
            console.warn("OpoInstall SDKが利用できません。フォールバックナビゲーションが有効化されました。");
            isSdkBlocked = true;
            restoreInstallButton();
        }
    });
    </script>
</body>
</html>

ステップ 3：紹介パラメータの復元とアカウントの紐付け

初回アプリ起動時の紹介コンテキストの取得

インストール後、アプリケーションはプラットフォームとデプロイされたアトリビューションSDKによってサポートされているメカニズムを使用して、紹介コンテキストの取得を試みる必要があります。

WebランディングページのURLに存在するパラメータが、アプリストアのインストールを自動的に生き残ると仮定しないでください。

Androidでは、インストールパスと構成された参照元ペイロードがそれをサポートしている場合、アプリケーションはGoogle Play Install Referrerを使用できます。サードパーティのアトリビューションSDKが追加の取得APIを提供している場合は、使用中の正確なSDKバージョンに対してそのメソッドシグネチャ、コールバック動作、およびペイロードスキーマを検証してください。

iOSでは、直接のユニバーサルリンク処理とインストール後の紹介復元は別個のフローとして扱う必要があります。アプリケーションは、遅延復元のために文書化された、プラットフォームで許可されているメカニズムを使用する必要があります。メカニズムを検証できない場合、または紹介コンテキストを復元できない場合は、インストールを紹介者にアトリビューションすることなくオンボーディングを続行してください。

非同期の取得とリトライ動作

紹介の取得によってメインUIスレッドがブロックされたり、ユーザーが登録を完了する妨げとなったりしてはなりません。取得操作は非同期として扱い、実際のSDKまたはアプリケーションサービスに適したタイムアウトを適用し、正常な復元、空の結果、タイムアウト、および失敗のそれぞれに対して明確な結果を記録します。

ドキュメント化されたSDKの動作とアプリケーションのオンボーディング要件に従ってタイムアウトを構成します。この例に示されているタイムアウト値は、関連するSDKドキュメントで明示的に確認されていない限り、ベンダーのデフォルトではなくアプリケーションレベルの構成です。

文書化されたAPIがサポートしており、アプリケーションに定義されたリトライポリシーがある場合は、リトライを試みることができます。登録が完了した後に遅れたコールバックが到着した際に、重複するアカウント紐付けリクエストを防ぎ、繰り返し報酬を発行することを避けてください。

サーバー側での紹介検証

クライアントから報告されたすべての紹介値を信頼できない入力として扱います。アプリケーションのバックエンドは、候補の紹介者トークンを検証し、被紹介者の適格性を確認し、紐付けを作成する前に紹介プログラムのビジネスルールを適用する必要があります。

データベースレベルの一意性制約または同等のトランザクション制御を使用して、同じ被紹介者に対する複数の紹介者紐付けを防ぎます。紹介の紐付けを報酬の発行から切り離し、必要な有効化マイルストーンがサーバー側で検証された後にのみ報酬を解放します。

WeChat、LINE、WhatsAppにおけるアプリ内ブラウザの制限の管理

コンテナのサンドボックスバリア：メッセージングアプリがカスタムスキーマや直接APKダウンロードを傍受する仕組み

バイラル紹介シェアの大半は、モバイルメッセージングアプリケーション内で発生します。しかし、WeChat、LINE、WhatsAppなどのプラットフォームは、OSのバージョンやコンテナのセキュリティポリシーに応じて、直接バイナリのダウンロードやディープリンクスキーマを頻繁に傍受、制限、または変更するサンドボックス化されたアプリ内webview内で外部Webリンクを表示します。

招待されたユーザーがアプリ内ブラウザ内で紹介リンクをタップした場合：

• 直接のAPKダウンロードが傍受される: Androidでは、Webランディングページから直接.apkバイナリファイルをダウンロードしようとする試みが、webviewコンテナによって頻繁に傍受またはブロックされます。
• カスタムURLスキームがブロックされる: プライベートなURLスキーム（myapp://invite?code=123）の呼び出しが実行に失敗することが多く、すでにアプリをインストールしているユーザー向けの写真の直接のネイティブアプリ起動が妨げられます。
• ユニバーサルリンクが抑制される可能性がある: 一部のメッセージングアプリケーションはアウトバウンドのナビゲーションを傍受し、標準的なiOSのユニバーサルリンクがオペレーティングシステムに向けて外部解決されるのを防ぎます。

アプリ内ユーザーエージェントヘッダーの検出

これらのコンテナの制限に優雅に対応するため、シェアランディングページは、初期DOM読み込み時に着信するブラウザのUser-Agent文字列を検査する必要があります。

• WeChatの検出: navigator.userAgent内のMicroMessengerを検査する。
• LINEの検出: navigator.userAgent内のLine/を検査する。
• WhatsAppの検出: navigator.userAgent内のWhatsAppを検査する。
• Facebook / Messenger / Instagramの検出: navigator.userAgent内のFBAVまたはInstagramを検査する。

リダイレクト戦術の評価：直接アプリへの引き渡し vs システムブラウザへの移行

オペレーティングシステムとソーシャルアプリケーションは、明確なナビゲーション動作を示します。

• WeChatおよびLINE環境: これらのコンテナは、直接のバイナリダウンロードと外部スキームの実行を制限します。自動リダイレクトを試みると、プラットフォームの警告画面が頻繁にトリガーされます。ランディングページには、デバイスのデフォルトシステムブラウザ（iOSではSafari、AndroidではChrome）でリンクを開くようユーザーに促す明示的な視覚的ガイダンスが表示されます。
• WhatsApp環境: 近年のiOSおよびAndroidの実装では、WhatsAppは通常、システム提供のアプリ内ビューポート（iOSのSFSafariViewControllerやAndroidのChrome Custom Tabsなど）でWebリンクを開きます。これらの環境では、標準的なWebナビゲーションが許可され、プラットフォームのアプリストアへの移行がサポートされますが、カスタムURLスキームには依然として明示的なユーザータップが必要になる場合があります。

丁寧なユーザーガイダンスの実装：直接リダイレクトが失敗した際のネイティブメニュープロンプトのオーバーレイ

アプリ内webviewがプログラムによる外部への引き渡しを防ぐ場合、ランディングページは視覚的なユーザーガイダンスを展開します。

• 条件付きマスクオーバーレイ: MicroMessengerまたはLine/が検出された場合、画面の右上隅を指し示すコントラストの高い視覚的オーバーレイを表示します。
• 明示的なアクションコピー: プロンプトはユーザーに次のように指示します。「右上隅のメニュー（•••）をタップし、『ブラウザで開く』（Safari / Chrome）を選択してアプリをダウンロードしてください。」
• パラメータ状態の保持: 中間リダイレクトによって削除されない限り、ユーザーが同じURLを読み込むことで外部ブラウザに移行した場合でも、アドレスバー内のクエリパラメータ（?shareCode=...）はそのまま維持されます。ランディングページがSafariまたはChromeで再読み込みされると、Web JS SDKがクリーンに実行され、紹介コンテキストがステージングされます。

ソーシャルファネル全体での紹介パラメータ脱落のトラブルシューティング

積極的なアプリ内リンクシミングプロキシ全体でのパラメータ削除の診断

一部のソーシャルプラットフォームは、共有された外部リンクを中間リンクのラッピングまたはシミングドメイン（Facebookのl.facebook.comやTwitterのt.coなど）経由でルーティングします。場合によっては、これらのリダイレクトホップによって非標準のクエリパラメータが削除されたり、競合する内部クリック識別子（fbclid）が追加されたりします。

マルチホップのソーシャルリダイレクト全体でパラメータの損失を防ぐには：

• 標準パラメータ命名: IETF RFC 3986に従い、shareCodeやchannelCodeなどの標準的な英数字クエリキーを使用します。
• 事前フライトリンク検証: ターゲットのメッセージングネットワーク上のライブチャットセッションでリンクの解像度をテストし、最終的なランディングページのwindow.location.searchを検査して、shareCodeパラメータがすべての中間リダイレクトを生き残っていることを確認します。

デスクトップWebシェアの処理：ユーザーがPCブラウザでモバイル紹介リンクを開いた場合

紹介キャンペーンはモバイルデバイス向けに設計されていますが、ユーザーはデスクトップコンピュータ（WhatsApp Web、Mac/Windows版WeChat、Slackなど）でチャットリンクを開くことがよくあります。デスクトップユーザーがモバイルダウンロードのランディングページにアクセスした場合、モバイルストアへのリダイレクトは失敗します。

エンタープライズ向けのランディングページは、レスポンシブな劣化によってデスクトップトラフィックを処理します。

• デスクトップ環境の検出: Web JS SDKがデスクトップオペレーティングシステム（Windows、macOS、Linux）を検出します。
• 動的QRコード生成: クリックできないモバイルストアボタンを表示する代わりに、レスポンシブテンプレートはデスクトップのビューポート上に条件付きでQRコードコンテナを表示できます。
• クロスデバイススキャン: ユーザーはモバイルデバイスでデスクトップ画面のQRコードをスキャンします。QRコードは元のshareCodeを含む宛先URLをエンコードし、紹介セッションをデスクトップからモバイルへ転送します。

オペレーティングシステムのペーストボードアクセス制限の緩和

オペレーティングシステムのプライバシーコントロールがクリップボードへのアクセスを管理します。

• Androidのフォアグラウンドフォーカスルール: Android 10（APIレベル29）以降では、バックグラウンドアプリケーションはAndroid ClipboardManagerを介してクリップボードデータを読み取ることはできません。ネイティブSDKは、アプリケーションのメインアクティビティがアクティブなウィンドウフォーカスを取得するまで、クリップボードの検査を遅延させる必要があります。
• iOSペーストボードプロンプト: iOS 16以降では、Apple UIPasteboardへのプログラムによるアクセスにより、ソースブラウザからの貼り付けを許可するかどうかを尋ねるシステムの通知やプロンプトがトリガーされる場合があります。
• ネットワークフォールバックの調整: アトリビューションアーキテクチャは、ローカルのクリップボードバッファを日和見的な拡張機能として扱い、ペーストボードの読み取りが拒否されたり利用できない場合にはサーバー側のセッションマッチングにフォールバックすることで、これらの制限に対応します。

物理デバイス間でのソーシャル紹介ファネルの事前フライト検証プロトコル

顧客紹介キャンペーンを立ち上げる前に、グロースエンジニアリングチームは以下の体系的な検証チェックリストを実行する必要があります。

Androidのターゲットシェアフォールバック: WeChatやLINEがインストールされていない場合、アプリがシステムシェアチューザーに正しくフォールバックすることを確認します。
• Androidのクリップボードリンクコピーフォールバック: システムシェアチューザーが失敗したり例外をスローしたりした場合に、完全な紹介リンクがクリップボードにコピーされ、トースト通知が表示されることを確認します。
• H5 SDKの遅延と1回限りのナビゲーション: SDKの初期化遅延が1500msを超えた場合に、フォールバックナビゲーションがクリーンに実行され、遅れて届いたonreadyイベントが重複したナビゲーションをトリガーしないことをシミュレートして確認します。
• H5パラメータとフラグメントの保持: 既存のクエリパラメータ、重複キー、および#fragmentsを含むURLを使用して、ランディングページのフォールバックナビゲーションをテストし、クリーンなパラメータ置換が行われることを確認します。
• iOSのユニバーサルリンクとストアへの引き渡し: 既存ユーザー向けの直接アプリ起動をテストし、インストール後のパラメータ復元をAppleのアンチフィンガープリンティング規則と照らし合わせて評価します。
ライブソーシャルメッセージングのディスパッチ: アクティブなWeChatやLINEのチャットセッションにリンクをディスパッチし、アプリ内ブラウザの検出オーバーレイがshareCodeをドロップすることなくSafariまたはChromeへユーザーを誘導することを確認します。
• バックエンドの紐付けと報酬の冪等性（イデムポテンシー）: アプリケーションのバックエンドが候補トークンを受け入れ、重複する紐付けを拒否し、検証済みのマイルストーンが完了するまで報酬を保留状態に保持することを確認します。

紹介トラッキングアーキテクチャの比較分析

紹介トラッキングアーキテクチャの比較

実装の複雑さ、コンバージョン摩擦、およびアトリビューション精度のトレードオフ

手動のプロモーションコードは比較的簡単に実装できますが、ユーザーがコードを入力して換金する必要があります。これにより摩擦が生じ、本来の紹介関係の範囲外でコードが共有される機会が生まれます。

デバイスフィンガープリンティングはユーザーのインタラクションを削減するように見える場合がありますが、その信頼性はマッチングの実装と利用可能なシグナルに依存します。Appleによる禁止されたフィンガープリンティングの制限を含め、適用されるプライバシー要件と矛盾する場所で使用してはなりません。

明示的な紹介パラメータは、意図された紹介者のビジネスレベルでの明確な表現を提供します。しかし、Web URLでトークンを運ぶことは、アプリストアのインストール後にそのトークンを復元することと同等ではありません。ソリューション全体として、パラメータの連続性、プラットフォームがサポートする復元メカニズム、およびサーバー側の検証を組み合わせる必要があります。復元が失敗した場合は、未検証の紹介者に割り当てるのではなく、インストールをアトリビューションなしのままにする必要があります。

まとめと決定フレームワーク

自動モバイル紹介トラッキングは、Webシェアフローを通じて明示的な紹介者トークンを運搬し、アプリケーションのバックエンド上で結果の紹介関係を検証することにより、手動の紹介コード入力を削減できます。

信頼性の高い実装には、shareCodeクエリパラメータを追加する以上のことが求められます。ランディングページはサポートされているリダイレクトを通じてトークンを保持し、アプリケーションは関連するプラットフォームに対して検証済みの復元メカニズムを使用し、バックエンドはアカウントの適格性を検証して冪等な紐付けと報酬の発行を強制する必要があります。

AndroidとiOSは個別に評価する必要があります。Google Play Install ReferrerはAndroidでサポートされているインストールメタデータを提供できます。iOSでは、アプリケーションがインストールされている場合にユニバーサルリンクが直接ルーティングをサポートしますが、App Storeのインストール後の遅延パラメータ復元を自動的に保証するものではありません。追加の復元メカニズムはすべて、ドキュメント化され、テストされ、適用されるプラットフォームのプライバシー要件に照らしてレビューされる必要があります。

本番環境へのデプロイに向けては、統合する正確なバージョンに対してすべてのSDKメソッド名、構成値、チャネル識別子、およびコールバックスキーマを検証してください。クリーンなデバイス上およびターゲットのメッセージングアプリケーション内で完全なジャーニーをテストしてください。サポートされているメカニズムを通じて紹介を復元できない場合は、未検証の紹介関係を作成するのではなく、オンボーディングを進め、結果をアトリビューションなしとして記録してください。

OpoInstallのSDKおよび開発者ドキュメントは、このアーキテクチャを実装するためのコンポーネントを提供する場合があります。本番の紹介キャンペーンで依存する前に、デプロイされたリリースでサポートされている特定の機能とプラットフォームの動作を確認してください。

統合の詳細については、OpoInstall開発者ドキュメント、OpoInstall SDKダウンロードセンター、およびOpoInstall開発者コンソールを参照してください。対応する公式のAndroidおよびAppleプラットフォームのドキュメントを使用して、アプリケーションに関連するインストールとプライバシーの動作を検証してください。

関連資料

• 概念: 自動紹介トラッキング、紹介者と被紹介者の紐付け、遅延ディープリンク、アプリ内Webviewサンドボックス

• 技術: モバイルアトリビューションSDK、Web JS SDK、ユニバーサルリンク（Universal Links）、Android App Links、S2Sポストバック

• 標準: IETF RFC 3986 汎用リソース識別子（URI）汎用構文、W3CクリップボードAPIおよびイベント仕様

• 統合インターフェース: アプリケーションが所有するシェア意図テレメトリ、デプロイされたSDKバージョンの文書化されたインストール参照元またはアトリビューションAPI、プラットフォーム固有のディープリールーティング、およびサーバー側の紹介検証。

• 公式ドキュメントと参考資料:

  • Appleのユーザープライバシーとデータ利用のガイダンス

  • Google Play Install Referrer APIドキュメント

  • Android 11におけるパッケージの可視性に関するGoogle Androidデベロッパーガイド

  • ClipboardManagerとフォーカス要件に関するGoogle Androidデベロッパーガイド

  • OWASPモバイルトップ10セキュリティリスクとガイドライン