ドキュメント

デバイスアトリビューションの検証

Singular Device AssistアプリとAttribution Details APIエンドポイントを使用してデバイスのアトリビューションを検証し、統合テストとトラッキングリンクの検証を行うための包括的なガイドです。

Singularでは、デバイスのアトリビューションを確認するための2つの方法を提供しています：モバイルテスト用のDevice Assistアプリと、プログラムによる検証用のAttribution Details APIエンドポイントです。

アトリビューションの検証は、新しいSDK/S2S統合のテストや、キャンペーン展開前のSingularリンクの検証に不可欠です。

対象者	UAマネージャー、開発者、QAエンジニア
前提条件	テスト用モバイルデバイス（デバイスアシストアプリメソッド） Singular APIキー（APIエンドポイント方式）デバイス広告識別子（IDFA、IDFV、GAIDなど）

アトリビューション検証のユースケース

アトリビューション検証のタイミング

デバイスのアトリビューション検証は、統合およびキャンペーン展開のライフサイクルの複数の段階で重要です。

ユースケース	目的
SDK/S2S統合テスト	統合開発中に、SDKがインストールを適切に追跡し、正しいソースに帰属することを検証します。完全なテストコンソールガイド
トラッキングリンクの検証	キャンペーンのデプロイ前に新しいシンギュラーリンクをテストし、適切なアトリビューションとパラメータの受け渡しを確認します。トラッキングリンクのテスト方法
キャンペーンのトラブルシューティング	テストデバイスのアトリビューションステータスを確認することで、ライブキャンペーンにおけるアトリビューションの問題を診断します。
パートナー統合の検証	広告パートナーからSingularプラットフォームへアトリビューションデータが正しく流れることを確認します。

検証方法の比較

検証方法の選択

テスト要件と技術的能力に基づき、適切な検証方法を選択します。

検証方法	最適な検証方法	要求事項	制限事項
デバイス支援アプリ	迅速な手動テスト非技術系ユーザー視覚的検証	モバイルデバイスアプリのインストール	手動プロセス、限られた自動化
属性詳細API	自動テストプログラムによる検証 CI/CD統合	APIキーデバイス識別子 HTTPクライアント	テストのみ（ベータ版）、技術的知識が必要

方法 1: デバイスアシストアプリ

デバイスのアトリビューションステータス、インストールの詳細、イベントトラッキングのサマリーをテストデバイス上で直接視覚的に素早く確認できるモバイルアプリ。

デバイス・アシストアプリの概要

アプリの機能

デバイスアシストアプリは、特定のデバイスについてSingularに記録された包括的なアトリビューション情報を表示します。

表示されるアトリビューションデータ

インストールアトリビューション：インストールタイムスタンプ、アトリビューション対象ネットワーク、キャンペーン名
リエンゲージメントアトリビューション：再エンゲージメントのタイムスタンプ、帰属ネットワーク、キャンペーン詳細
イベントサマリー：Singularによってトラッキングされたセッションとアプリ内イベント。
デバイス識別子：IDFA、IDFV、GAID、またはトラッキングに使用されるその他の識別子

デバイスアシストアプリの使用

ステップごとの手順

1	デバイスアシストアプリのダウンロード Singular Device Assistアプリをテストデバイスにインストールします： iOS:App Storeからダウンロード Android:Google Playからダウンロード
2	アトリビューションチェックの起動 Device Assistアプリを開き、メインメニューからCheck Implementationを選択します。追加機能：デバイスアシストアプリは、メインメニューからアクセス可能なデバイス識別子ルックアップおよびSDK実装検証ツールも提供します。
3	デバイス識別子を選択アプリが自動的にプラットフォームに適切なデバイス識別子を選択します。選択を確認し、[Check Implementation]をもう一度タップして次に進みます。識別子の選択： iOS：IDFA（ATTが認可している場合）またはIDFV（ATTが認可していない場合、または実装されていない場合 Androidの場合GAID（グーグル広告ID）またはGAIDが利用できない場合の代替識別子
4	アトリビューションの詳細を確認するアプリは、Singularプラットフォームに記録されたデバイスの完全なアトリビューション情報を表示します。表示されるアトリビューション情報アトリビューションの詳細をインストール # インストールタイムスタンプ：アプリを最初に起動した日時（インストールイベントアトリビューションネットワーク：インストールにクレジットされた広告ネットワークまたはソース（Facebook、Google広告、オーガニックなどキャンペーン名：インストールに起因するマーケティングキャンペーン追加パラメータ：トラッキングリンクから渡されるキャンペーン固有のパラメータインストールのアトリビューションの解釈「オーガニックアトリビューションウィンドウ内に一致するタッチポイントがない - インストールは有料キャンペーンに起因しない「未アトリビューション」：デバイスは追跡されているが、アトリビューション決定が保留中または不完全ネットワーク名：インストールが特定の広告パートナーに正常に帰属リエンゲージメントアトリビューションの詳細 # リエンゲージメントタイムスタンプ：最新のリエンゲージメントセッションの日時帰属ネットワーク：ユーザーをアプリに戻したソースキャンペーン名：キャンペーン名: セッションに起因するリエンゲージメントキャンペーン自己帰属ネットワーク:自己帰属ネットワーク（Twitter、Facebook、Google Ads、Snapchatなど）からのリエンゲージメント帰属は、プライバシー上の理由から「未帰属」と表示される場合があります。リエンゲージメント帰属の要件リエンゲージメントアトリビューションが発生するにはユーザーは既にインストールされている必要があります。リエンゲージメントキャンペーンのクリックは、設定されたアトリビューションウィンドウ内で発生する必要があります。リエンゲージメントクリック後にセッションが発生すること詳細：リエンゲージメントアトリビューション FAQ イベントトラッキングの概要 # デバイスアシストアプリは、Singularがトラッキングしたすべてのアプリ内イベントのサマリーを表示します。表示されるイベント情報イベント名：トラッキングされたイベント名（セッション、購入、レベルコンプリートなど最初のイベント発生時刻:最初のイベント発生のタイムスタンプ最終イベント時間:最新のイベントのタイムスタンプイベント回数：イベントの合計発生回数収益：収益イベントの総収益イベントトラッキングの検証イベントサマリーを使用して検証します：セッションが正しくトラッキングされているカスタムイベントが正しい名前で表示されている収益イベントが金額を正しく捕捉しているイベントのタイムスタンプが実際のユーザーアクションと一致している

デバイス・アシストのトラブルシューティング

よくある問題

アトリビューションデータが表示されない

考えられる原因

アプリがインストールされていない：テストアプリがインストールされていないか、デバイス上でまだ開かれていない
誤った識別子：アプリSDKで使用されていない識別子をチェックするデバイスアシスト
SDKが初期化されていない：アプリでSingular SDKが適切に初期化されていない
アトリビューション未決定：アトリビューション決定がまだ確定していない（通常1～5分かかる

解決手順

テストアプリがインストールされ、デバイス上で少なくとも1回は開いていることを確認する。
デバイスの識別子がSDKで使用されている識別子の種類と一致していることを確認（iOSのIDFAとIDFVの比較
アプリの起動後5～10分待ち、帰属を再度確認する。
テストコンソールを使用してSDKの統合を確認する

誤ったソースへの帰属

考えられる原因

以前のデバイスの使用：キャッシュされたアトリビューションでテストに使用されたデバイス。
複数のタッチポイント：アトリビューションウィンドウ内での複数のキャンペーンクリック
フィンガープリントマッチング:確率的アトリビューションが誤ったクリックにマッチした

解決ステップ

デバイスをリセットし、アトリビューションをクリアします：
- テストアプリの削除
- 広告識別子をリセット
- 登録されている場合は、テストコンソールからデバイスを削除します。
テスト前に新しいデバイスを使用するか、識別子をリセットする
テストにはフィンガープリンティングではなく、決定論的アトリビューション（トラッキングリンクのデバイスID）を使用する。
パートナー設定のアトリビューションウィンドウの設定を見直す

キャンペーンの代わりにオーガニックとしてアトリビューションをインストールする

考えられる原因

アトリビューションウィンドウを超えた：設定したアトリビューションウィンドウの範囲外にインストールされた
一致するタッチポイントがない：一致するクリックが見つかりませんでした。
フィンガープリントの不一致：クリックとインストールの間にデバイスのフィンガープリントが変更された
リンクがクリックされていないトラッキングリンクをクリックせずにストアから直接アプリをインストール

解決ステップ

アプリをインストールする前にトラッキングリンクがクリックされたことを確認する
アトリビューションウィンドウの設定がインストールに十分な時間を与えていることを確認する
信頼性の高いテストのために、トラッキングリンクにデバイスIDを使用する（決定論的アトリビューション
クリックとインストール中に安定したネットワーク接続が確保されていること
別のデバイスでテストするか、識別子をリセットして再試行する。

方法2：アトリビューション詳細API

統合テストおよびCI/CDパイプラインの自動アトリビューション検証を可能にするプログラムAPIエンドポイント。

ベータ機能のお知らせ：Attribution Details API エンドポイントはベータ機能です。テスト目的でのみ使用してください - 本番アプリまたは大量の環境内で呼び出さないでください。

APIエンドポイントの仕様

リクエスト形式

エンドポイントURL

https://api.singular.net/api/attribution/attribution_details

リクエスト・メソッドGET

リクエスト例

https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here

クエリーパラメーター

必須パラメータ

パラメータタイプ説明

api_key

文字列

プラットフォームからのSingular Reporting API Key。

場所ダッシュボード → 開発者ツール → APIキー → レポートAPIキー

重要：SDKキーではなく、Reporting APIキーを使用してください。異なるキーは異なる目的を果たします。

device_id

文字列

デバイスの広告識別子値。

keyspace パラメータで指定された識別子タイプと一致する必要があります。

keyspace

文字列（Enum）

device_id で提供される広告識別子のタイプ：

idfa - 広告主用iOS識別子（ATTの認証が必要
idfv - iOS Identifier for Vendors（IDFAが利用できない場合の代替）。
aifa - 広告用Android識別子（GAIDとしても知られる
sdid - ウェブトラッキング用のSingularデバイスID（SDK初期化後にsingularSdk.getSingularDeviceId()で取得

APIレスポンス

レスポンス形式

APIは、要求されたデバイスの属性詳細を含むJSON配列を返します。

サンプルレスポンス

[
  {
    "app_long_name": "com.example.myapp",
    "app_name": "My App",

    "install_info": {
      "install_time": "2020-06-10 11:58:46",
      "network": "Network 1",
      "additional_parameters": {
        "kw": "my keyword",
        "pcid": "1234"
      },
      "campaign_name": "Campaign Name",
      "view_through_attribution": false
    },

    "re_engagement_info": {
      "notes": "Attributions from Self-Attributing networks including: Twitter, Facebook, Google Ads, Snapchat, etc are redacted and always show as 'Unattributed'",
      "install_time": "2020-06-15 15:27:12",
      "network": "Unattributed"
    },

    "uninstall_pre_requisites": {
      "gcm_token": "enE8iQR10RI:APA91bERgfA_xm8T7zgqH9OW_1s05SFFmKnle1zIm0cMrDfuaSxEmC_3j72dj4qN36vh5V8TAEnrXa3Pq3SmLW-XNOHP7daMwcBrBTibdkv_pKMJbN9SbefV6_9nuEfIeI5Zhtz0nlLY"
    },

    "events": [
      {
        "event_name": "Session",
        "first_event_time": "2020-04-02 00:09:55",
        "last_event_time": "2020-04-07 20:59:55",
        "event_count": 2
      },
      {
        "event_name": "Save New Transaction",
        "first_event_time": "2020-04-02 00:11:51",
        "last_event_time": "2020-04-02 00:11:51",
        "event_count": 1
      }
    ]
  }
]

レスポンスパラメータ

JSON レスポンスのフィールド

フィールド	説明
`app_long_name`	アプリバンドル識別子（例：com.example.myapp）
`app_name`	Singularプラットフォームで設定されたアプリの表示名
`install_info`	インストール属性の詳細と決定情報を含むオブジェクト： `install_time` - 最初のアプリセッション（インストール）のタイムスタンプ `network` - インストールにクレジットされた広告ネットワーク `campaign_name` - インストールに起因するキャンペーン名 `view_through_attribution` - 広告インプレッション（true）と広告クリック（false）に基づくアトリビューションを示すブール値。詳細はこちら：Singularのインストールアトリビューションプロセス `additional_parameters` - トラッキングリンクから渡されるカスタムパラメータ。詳細：トラッキングリンクパラメータとレポートディメンション
`re_engagement_info`	`install_info` と同じ構造を持つオブジェクトですが、リエンゲージメントアトリビューション用です。詳細：リエンゲージメントアトリビューションFAQ プライバシーに関する注意：自己アトリビューションネットワーク（Facebook、Google Ads、Twitter、Snapchat）からのリエンゲージメントアトリビューションは、プライバシーコンプライアンスのため、"Unattributed "として表示されます。
`events`	SDKによってトラッキングされたアプリ内イベントサマリーを含むオブジェクトの配列： `event_name` - トラッキングされたイベント名 `first_event_time` - 最初に発生したイベントのタイムスタンプ `last_event_time` - 最新の発生のタイムスタンプ `event_count` - イベント発生総数 `revenue` - 収益イベントの収益合計（該当する場合
`uninstall_pre_requisites`	アンインストール・トラッキング・コンフィギュレーションを含むオブジェクト： `apns` (iOS) - Apple Push Notification Service トークン。設定:iOS アンインストールトラッキング。 `gcm_token` (Android) - Firebase Cloud Messaging トークン。設定:Android アンインストール追跡

API の使用例

実装例

iOS デバイス (IDFA)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here"

Android デバイス (GAID)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=aifa&device_id=12345678-1234-1234-1234-123456789012&api_key=your_api_key_here"

ウェブトラッキング (SDID)

curl -X GET "https://api.singular.net/api/attribution/attribution_details?keyspace=sdid&device_id=singular_device_id_value&api_key=your_api_key_here"

Python実装

import requests
import json

def check_attribution(keyspace, device_id, api_key):
    """
    Check device attribution using Singular API
    
    Args:
        keyspace: Device identifier type (idfa, idfv, aifa, sdid)
        device_id: Device identifier value
        api_key: Singular Reporting API key
    
    Returns:
        Attribution data as JSON or None if error
    """
    url = "https://api.singular.net/api/attribution/attribution_details"
    
    params = {
        'keyspace': keyspace,
        'device_id': device_id,
        'api_key': api_key
    }
    
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error checking attribution: {e}")
        return None

# Example usage
attribution_data = check_attribution(
    keyspace='idfa',
    device_id='12345678-1234-1234-1234-123456789012',
    api_key='your_api_key_here'
)

if attribution_data:
    print(json.dumps(attribution_data, indent=2))
    
    # Extract install info
    if attribution_data and len(attribution_data)  0:
        install_info = attribution_data[0].get('install_info', {})
        print(f"\nInstall Network: {install_info.get('network')}")
        print(f"Campaign: {install_info.get('campaign_name')}")
        print(f"Install Time: {install_info.get('install_time')}")

JavaScript実装

/**
 * Check device attribution using Singular API
 * 
 * @param {string} keyspace - Device identifier type (idfa, idfv, aifa, sdid)
 * @param {string} deviceId - Device identifier value
 * @param {string} apiKey - Singular Reporting API key
 * @returns {Promise} Attribution data or error
 */
async function checkAttribution(keyspace, deviceId, apiKey) {
    const url = 'https://api.singular.net/api/attribution/attribution_details';
    
    const params = new URLSearchParams({
        keyspace: keyspace,
        device_id: deviceId,
        api_key: apiKey
    });
    
    try {
        const response = await fetch(`${url}?${params.toString()}`);
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('Error checking attribution:', error);
        throw error;
    }
}

// Example usage
checkAttribution(
    'idfa',
    '12345678-1234-1234-1234-123456789012',
    'your_api_key_here'
)
.then(data = {
    console.log('Attribution Data:', JSON.stringify(data, null, 2));
    
    // Extract install info
    if (data && data.length  0) {
        const installInfo = data[0].install_info || {};
        console.log('\nInstall Network:', installInfo.network);
        console.log('Campaign:', installInfo.campaign_name);
        console.log('Install Time:', installInfo.install_time);
    }
})
.catch(error = {
    console.error('Failed to check attribution:', error);
});

APIのトラブルシューティング

よくあるAPIの問題

空の配列の応答

問題

API が属性データの代わりに空の配列[] を返す。

考えられる原因

アトリビューションデータがない：デバイスにアプリがインストールされていないか、セッションがトラッキングされていない
識別子が間違っている：デバイスIDまたはキースペースが正しくない
タイミングの問題：アトリビューションデータがまだ処理されていない（通常、インストールから1～5分後

解決手順

デバイスIDが余分なスペースなしで正しくコピーされていることを確認する。
キースペースが識別子の種類と一致していることを確認する（iOSの場合、idfaとidfvの違い
アプリのインストール後、5～10分待ってからクエリを再試行する。
Device Assistアプリを使用してデバイスの属性を確認し、アプリがインストールされ追跡されていることを確認する。

認証エラー

問題

APIが認証エラーまたは401 Unauthorized応答を返す。

考えられる原因

無効なAPIキー：APIキーが間違っているか、提供されていない
キータイプが正しくない：レポートAPIキーではなくSDKキーを使用している
キーの有効期限切れ：APIキーの失効または再生成

解決手順

ダッシュボード → 開発者ツール → APIキー → レポートAPIキーに移動します。
レポートAPIキー（SDKキーではない）をコピーします。
リクエストにAPIキーが正しく貼り付けられていることを確認する
キーが最近再生成された場合は、新しいキー値を使用していることを確認します。

セキュリティ上の警告APIキーをバージョン管理にコミットしたり、クライアント側のコードで公開したりしないでください。環境変数または安全な構成管理を使用してください。

レート制限エラー

問題

APIが429 Too Many Requestsまたはレート制限エラーを返す。

考えられる原因

過剰なリクエスト：短時間にAPIコールが多すぎる
本番環境での使用：APIが本番環境で使用されている（意図されたユースケースではない

解決策

指数関数的バックオフとリトライのロジックをコードに実装する
APIリクエストの間隔を空ける（コール間隔は最低1秒を推奨
APIコールを減らすために、可能な限りアトリビューションデータをキャッシュする。
合法的なテストでより高いレート制限が必要な場合は、Singularサポートにお問い合わせください。

ベータ版の制限：Attribution Details APIはテスト専用です。リクエスト量の多い本番アプリケーションでは使用しないでください。

ベストプラクティス

統合テストやキャンペーン検証時に効果的なアトリビューション検証のための推奨事項。

テストワークフロー

推奨されるテストプロセス

新しいデバイスを使用する：キャッシュされたアトリビューションを避けるため、テスト前にクリーンなデバイスでテストするか、広告識別子をリセットする。
すぐに検証する：インストール後5～10分以内にアトリビューションを確認し、テスト中に素早くフィードバックする。
複数のシナリオをテストする：異なるソース（オーガニック、有料キャンペーン、リエンゲージメント）のアトリビューションを検証する。
結果の文書化：アトリビューションの検証結果を記録し、統合検証の文書化を行う
可能な限り自動化する：継続的な検証のために自動化されたテストスイートでAttribution Details APIを使用する

メソッド選択ガイド

各手法を使用するタイミング

シナリオ	推奨される方法
迅速な手動テスト	デバイスアシストアプリ - 開発中の最速目視検証
自動テスト	Attribution Details API - CI/CDパイプラインでのプログラムによる検証
非技術的テスト	デバイスアシストアプリ - コーディングやAPIの知識が不要
バッチデバイス検証	Attribution Details API - 複数のデバイスチェックをスクリプト化
イベントトラッキング検証	両方の方法 - デバイス・アシストによる迅速なチェック、APIによる詳細なイベント分析

統合検証チェックリスト

アトリビューション検証チェックリスト

完全な帰属検証：

正しいネットワーク/ソースに帰属するインストール
キャンペーン名が予想されるキャンペーンと一致
アトリビューションのタイムスタンプが妥当（予想される時間枠内）
アトリビューション方法が適切である（クリック対インプレッション）
トラッキングリンクを通じてカスタムパラメータが正しく渡された
セッションイベントが適切にトラッキングされている
カスタムイベントが正しい名前で表示されている
収益イベントが金額と通貨を捕捉している
リエンゲージメントアトリビューションが機能している（該当する場合）
アンインストールトラッキングの設定（実装されている場合）

その他のリソース

アトリビューション・テスト、SDK統合、トラッキング・リンク設定に関する完全なドキュメント。

デバイスの帰属を確認する方法

デバイスアトリビューションの検証

アトリビューション検証のユースケース

アトリビューション検証のタイミング

検証方法の比較

検証方法の選択

方法 1: デバイスアシストアプリ

デバイス・アシストアプリの概要

アプリの機能

デバイスアシストアプリの使用

ステップごとの手順

デバイスアシストアプリのダウンロード

アトリビューションチェックの起動

デバイス識別子を選択

アトリビューションの詳細を確認する

表示されるアトリビューション情報

インストールのアトリビューションの解釈

リエンゲージメント帰属の要件

イベントトラッキングの検証

デバイス・アシストのトラブルシューティング

よくある問題

考えられる原因

解決手順

考えられる原因

解決ステップ

考えられる原因

解決ステップ

方法2：アトリビューション詳細API

APIエンドポイントの仕様

リクエスト形式

クエリーパラメーター

必須パラメータ

APIレスポンス

レスポンス形式

サンプルレスポンス

レスポンスパラメータ

JSON レスポンスのフィールド

API の使用例

実装例

iOS デバイス (IDFA)

Android デバイス (GAID)

ウェブトラッキング (SDID)

Python実装

JavaScript実装

APIのトラブルシューティング

よくあるAPIの問題

問題

考えられる原因

解決手順

問題

考えられる原因

解決手順

問題

考えられる原因

解決策

ベストプラクティス

テストワークフロー

推奨されるテストプロセス

メソッド選択ガイド

各手法を使用するタイミング

統合検証チェックリスト

アトリビューション検証チェックリスト

その他のリソース

関連ドキュメント