Singular統合プラン
サードパーティデータ統合によって生成されたデータは、クラスターの消費データ量に含まれますのでご注意ください
概要
インターフェースの概要
| インターフェース名 | タイプ | 粒度 | アトリビューション | コスト | 収益 | 表示 | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|
| Internal BI Postbacks | コールバック | ユーザーレベル | ✅ | ✅ | ✅ |
Singularはパートナー設定によるコールバック機能を提供しています。この機能を使うと、アトリビューションデータ、広告収益、コンバージョンデータなどのユーザー粒度のデータをコールバックできます
Singularのデータの統合を始める前に、AEシステムのユーザー識別ルールを読み、AEが#distinct_idと#account_idによってユーザーを識別する仕組みを理解しておいてください
統合の流れ
- SingularクライアントSDKとAEクライアントSDKを導入し、Singular SDKでAEのユーザー識別IDを設定します
- AE管理画面にログインし、サードパーティ統合モジュールでSingularのコールバックプランを追加して、関連する設定を完了し、コールバックURLを取得します
- Singularの管理画面でInternal BIコールバックを追加します
- AEシステムがデータを正常に受信しているかを確認し、レポートを作成します
1. クライアントSDKの設定
SingularのコールバックデータをAEプロジェクトのユーザーデータと連携させるには、Singular SDKでAEプロジェクトのアカウントIDとゲストIDを送信する必要があります。
まずAE SDKを初期化し、Singular SDKの初期化時にAE SDKのゲストIDをSingularのカスタムユーザーIDとして設定することを強くお勧めします。以下はAndroidのコード例です：
// AE SDK を初期化する
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// AE のゲスト ID を取得する（AE の #distinct_id に対応）
String te_distinct_id = TDAnalytics.getDistinctId();
// SingularConfig に AE のゲスト ID をカスタムユーザー ID として渡し、初期化する
SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withCustomUserId(te_distinct_id);
Singular.init(context, config);
2. プランの設定
SDKの設定が完了したら、次にAEシステムの管理画面にログインし、「サードパーティ統合」モジュールでSingularプランの設定を完了します。下図はSingular Internal BI Postbacksプランの設定画面です：
2.1 ユーザー識別フィールド
Singular Internal BI Postbacksのデータはユーザーレベルのデータであるため、ユーザー識別ルール、つまりSingular SDKで設定したAEシステムのユーザー識別IDを設定する必要があります。AEシステムはこの設定に基づき、コールバックデータを変換する際に、これらのフィールドをデータのユーザー識別フィールドとして設定します。
本ドキュメントの前のステップに従ってクライアントSDKを設定した場合は、次の設定を使用してください：
- アカウントID関連フィールド：なし
- ゲストID関連フィールド：user_id
2.2 イベントデータの格納設定
「イベントデータの格納設定」スイッチをオンにすると、Singularがコールバックしたデータはすべてイベントテーブルに書き込まれます。イベントデータの格納を有効にすることをお勧めします。
2.3 ユーザープロパティの格納設定
デフォルトでは、AEシステムはSingularのデータをユーザープロパティに書き込みません。ユーザーのアトリビューション情報フィールドなど、一部のフィールドをユーザーテーブルに書き込みたい場合は、まずルールをオンにして実行させ、プロパティマッピング機能でユーザーテーブルに書き込むフィールドを追加します。ソースプロパティ名にはフィールドの格納名を入力します：
ユーザープロパティの格納ルールは、以下のように設定することをお勧めします：
- 「すべてのイベントを含む」をオフにする
- ソースイベント名の選択：singular_install
- 格納ルール：user_setOnce
- プロパティフィールドの設定は以下のとおりです：
| ソースデータ名 | ターゲットプロパティ名 | 説明 |
|---|---|---|
| network | te_ads_object.media_source | メディアチャンネル |
| tracker_campaign_name | te_ads_object.campaign_name | 広告キャンペーン名 |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | 広告グループ名 |
| tracker_creative_name | te_ads_object.ad_name | 広告名 |
2.4 統合構成
統合構成モジュールでは、データ取得の詳細な設定を制御できます。たとえば、格納後のイベント名などです
統合構成の内容はJSONです。次の内容に従ってカスタム設定できます：
| モジュール | 名前 | 意味 |
|---|---|---|
| sink_event | event_mapping | 格納後のイベント名。カスタマイズできます。KeyはSingularのコールバックデータのイベント名、Valueはそのイベントの格納後のイベント名です。ここに記載されていないイベントは、コールバックデータのイベント名の前にsingular_を付けたものが格納時のイベント名になります |
2.5 ターミナルアドレス
ターミナルアドレスには、AEシステムがSingularのコールバックデータを受信するアドレスが表示されます。このアドレスをそのままコピーし、この後のSingularのコールバック設定で入力してください：
ここにアドレスが表示されない場合は、右上のメニュー「プロジェクト管理 → プロジェクト設定 → プロジェクト構成」でパブリックネットワークURLを設定してください。このアドレスは、AE SDKで設定するデータ受信URLです。設定後、Singularの設定ページの「ターミナルアドレス」に戻ってターミナルアドレスをコピーしてください。
最後に、右上の保存ボタンをクリックしてSingularプランを保存するのを忘れないでください。
3. コールバックとデータ格納の設定
3.1 コールバックの設定
Singularのプランを作成したら、Singularの管理画面にログインし、Attribution > Partner Configuration（アトリビューション設定-チャネル設定）ページに移動します。チャネルパートナーの追加欄で「Thinking Data」を検索してクリックすると、AEシステムへのコールバック設定の追加を開始できます。
Configurationページに移動し、まずデータをコールバックするAppとSiteを選択します
次に、AEシステムのSingular統合プランのコールバックURLを、Postback URLに入力します
最後に、Singularはデフォルトでインストールイベント（install）とリエンゲージメントイベント（Re-Engagement）をコールバックします。アプリ内イベントもコールバックする必要がある場合は、上部のタブで「In app Events Postback」に切り替え、下のリストにコールバックするイベントを追加してください。収益イベントの場合は、Revenue Events Postbacksメニューで選択できます：
注意：SDKイベントリストには、以下の収益イベントの選択肢があります：
-
__IAP__は、カスタム名のないすべてのアプリ内購入イベントを指します
-
イベント名がそのまま表示される収益イベントは、名前を変更済みのアプリ内購入イベントを指します
-
__ADMON_USER_LEVEL_REVENUE__は広告収益イベントを指します（Ad Revenue Attributionを設定している場合）
-
__REVENUE__には以下が含まれます：
- すべてのアプリ内購入イベント（__IAP__とカスタムのアプリ内購入イベントを含む）
- 広告収益イベント（Ad Revenue Attributionを設定している場合）
- さらに、すべての収益データを1つのイベントにまとめてコールバックします
コールバックを設定する際は、アプリ内購入イベントがAE SDKですでに送信されているかどうかを確認してください。AE SDKでアプリ内購入イベントを送信済みの場合は、データの重複を避けるため、Singularから__IAP__やその他のアプリ内購入イベントをコールバックすることはお勧めしません
また、__REVENUE__はすべての収益イベントを1つのイベントにまとめるため、プロジェクトでアプリ内購入イベントと広告収益イベントの両方を記録している場合は、__REVENUE__を設定せず、収益イベントを1つずつ個別に設定することをお勧めします。これにより、アプリ内購入と広告収益化のデータをより適切に区別できます
3.2 イベントの格納ルール
-
データ内のuser_idフィールドを、ユーザーのゲストIDとして使用します
-
データ内のevent_utc_timestampフィールド、つまりイベントの発生時刻を、データの#event_timeとして使用します
-
データのイベント名は、データ内のevent_nameにプレフィックスsingular_を付けたものです。名前のない収益イベントは次のように命名されます：
- __IAP__：singular_iap
- __ADMON_ USER_LEVEL_REVENUE__：singular_ad_revenue
- __REVENUE__：singular_revenue
-
その他のフィールドはすべて格納されます。以下はInternal BI Postbacksでコールバックされるフィールドです：
| フィールド | 意味 |
|---|---|
| app_name | アプリ名 |
| longname | アプリのbundle ID |
| platform | OS。値はiOSまたはAndroid |
| event_name | イベント名 |
| idfa | iOSのIDFA |
| idfv | iOSのIDFV |
| aifa | Androidデバイスの広告識別子ID |
| android_id | Android ID。AIFAが利用できない場合にのみ送信されます |
| singular_id | （廃止）iOSデバイスでデータトラッキングが制限されている場合（LATがオンの場合）にのみ送信されます。Singularの内部IDを使用します |
| event_utc_timestamp | イベント発生時のUNIXタイムスタンプ |
| click_utc_timestamp | クリック時のUNIXタイムスタンプ |
| install_utc_timestamp | インストール時のUNIXタイムスタンプ |
| is_organic | 1はオーガニックユーザー、0は非オーガニックユーザーを表します |
| is_viewthrough | 1はビュースルーアトリビューションのユーザー、0はそれ以外を表します |
| network | ユーザーがアトリビューションされたメディアチャネル |
| campaign | Singularが識別したCampaign名 |
| campaign_group | Singularが識別したCampaignグループ名（一部のプラットフォームのみ） |
| creative | Singularが識別したクリエイティブ名またはクリエイティブID |
| site | Source site & Sub Site for click. Available if passed in click |
| user_id | カスタムユーザーID。2.1の設定に従い、値はAEシステムのゲストIDと同じになります |
| singular_click_id | Singularが生成した一意のクリックID |
| is_reengagement | 1はリエンゲージメント広告で復帰したユーザー、0はそれ以外を表します |
| click_ip | 広告クリック時のIPアドレス |
| os_version | 広告クリック時のOSバージョン |
| app_version | インストールまたはイベント発生時のアプリバージョン |
| country | ユーザーのインストール時の国（地域） |
| city | ユーザーのインストール時の都市 |
| limit_ad_tracking | 1はトラッキング制限がオン、0はそれ以外を表します |
| device_model | デバイスの機種 |
| device_brand | デバイスのブランド |
| match_type | アトリビューションのマッチング方式。値はdeterministic（デバイスIDによるマッチング、確定マッチング）、probabilistic（Android限定、推定マッチング）、or none（オーガニック）です。 |
| amount | 収益データの場合のみコールバックされます。米ドル建ての収益額 |
| currency | 収益データの場合のみコールバックされます。収益の通貨を表すISO 4217の3文字の通貨コード |
| is_first_event | 1はそのイベント（収益またはカスタムイベント）がそのデバイスの最初のイベントであること、0は最初のイベントではないことを表します |
| tracker_campaign_name | チャネルからコールバックされたCampaign名 |
| tracker_campaign_id | チャネルからコールバックされたCampaign ID |
| tracker_sub_campaign_name | チャネルからコールバックされたSub-campaign名 |
| tracker_sub_campaign_id | チャネルからコールバックされたSub-campaign ID |
| tracker_creative_name | チャネルからコールバックされたクリエイティブ名 |
| tracker_creative_id | チャネルからコールバックされたクリエイティブID |
| tracker_publisher_id | チャネルからコールバックされたハッシュ化済みのApp ID |
| tracker_publisher_sub_id | チャネルからコールバックされたPublisher SUB ID |
| tracker_publisher_site_name | チャネルからコールバックされたApp名 |
| tracker_publisher_site_id | チャネルからコールバックされたApp ID |
| tracker_publisher_sub_site_name | チャネルからコールバックされたSub-publisher名 |
| tracker_publisher_sub_site_id | チャネルからコールバックされたSub-publisher ID |
| tracker_name | トラッキングされたCampaign名 |
| network_tiktok_restricted | TikTokのビュースルーアトリビューションのユーザーデータには、この制限フィールドが含まれます。詳しくは付録を参照してください |
| campaign_tiktok_restricted | TikTokのビュースルーアトリビューションのユーザーデータには、この制限フィールドが含まれます。詳しくは付録を参照してください |
| fb_campaign_id | FacebookのCampaign ID。Facebookの利用規約による制限を受けます。詳しくは付録を参照してください |
| fb_campaign_name | FacebookのCampaign名。Facebookの利用規約による制限を受けます。詳しくは付録を参照してください |
| fb_adset_id | FacebookのAd Set（広告グループ）ID。Facebookの利用規約による制限を受けます。詳しくは付録を参照してください |
| fb_adset_name | FacebookのAd Set（広告グループ）名。Facebookの利用規約による制限を受けます。詳しくは付録を参照してください |
| fb_ad_id | Facebookの広告ID。Facebookの利用規約による制限を受けます。詳しくは付録を参照してください |
| fb_ad_name | Facebookの広告名。Facebookの利用規約による制限を受けます。詳しくは付録を参照してください |
| twitter_campaign_name | TwitterのCampaign名。Twitterの利用規約による制限を受けます。詳しくは付録を参照してください |
| twitter_campaign_id | TwitterのCampaign ID。Twitterの利用規約による制限を受けます。詳しくは付録を参照してください |
| twitter_line_id | TwitterのLine Item（広告グループ）ID。Twitterの利用規約による制限を受けます。詳しくは付録を参照してください |
| fraud_status | 不正トラフィックの判定結果。fraud postbacksを有効にしている場合のみコールバックされます。値は"valid"/"suspicious"/"rejected"（有効/疑わしい/拒否）です |
| fraud_reason | 不正トラフィックデータの判定ルール名。fraud postbacksを有効にしている場合のみコールバックされます |
3.3 標準化フィールド
Singularのコールバックデータの一部のフィールドについて、AEシステムは標準化処理を行います：
| フィールド | 標準化フィールド | 意味 |
|---|---|---|
| app_name | te_ads_object.app_name | アプリ名 |
| longname | te_ads_object.app_id | アプリID |
| platform | te_ads_object.platform | プラットフォーム（Android、iOSなど） |
| country | te_ads_object.country | 国・地域コード |
| amount | te_ads_object.revenue | マネタイズ収益 |
| currency | te_ads_object.currency | 収益の通貨 |
| network | te_ads_object.media_source | メディアチャンネル |
| tracker_campaign_name | te_ads_object.campaign_name | 広告キャンペーン名 |
| tracker_campaign_id | te_ads_object.campaign_id | 広告キャンペーンID |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | 広告グループ名、マネタイズ広告のUnit名 |
| tracker_sub_campaign_id | te_ads_object.ad_group_id | 広告グループID、マネタイズ広告のUnit ID |
| tracker_creative_name | te_ads_object.ad_name | 広告名 |
| tracker_creative_id | te_ads_object.ad_id | 広告ID |
4. 付録
一部のプラットフォームは、ユーザー粒度のデータを他のサードパーティプラットフォームにコールバックすることを制限しています。Internal BI Postbacksを使ったAEシステムへのコールバックもこれに含まれます。以下の表は、これらのプラットフォームの制限ルールです：
| プラットフォーム名 | 制限ルール |
|---|---|
| Facebookのユーザー粒度のデータはアトリビューションから6か月後に消去されます。そのため、アトリビューションから6か月が経過すると、Facebookでアトリビューションされたユーザーは、Singularシステムで "Organic"（オーガニック）として識別されます。また、Facebookのビュースルーアトリビューションのユーザー粒度データを取得することはエンドユーザー契約で認められていないため、Facebookのビュースルーアトリビューションのユーザーのアトリビューション情報はすべて "Unattributed" としてマークされます | |
| Google Ads (Adwords) | Google Adsのユーザー粒度のデータはアトリビューションから6か月後に消去されます。そのため、アトリビューションから6か月が経過すると、Google Adsでアトリビューションされたユーザーは、Singularシステムで "Organic"（オーガニック）として識別されます |
| Snapchat | Snapchatのデータ共有ポリシーでは、Snapchatのデータをサードパーティと共有することが一切禁止されています |
| TikTok | TikTokのユーザー粒度のデータはアトリビューションから6か月後に消去されます。そのため、アトリビューションから6か月が経過すると、TikTokでアトリビューションされたユーザーは、Singularシステムで "Organic"（オーガニック）として識別されます。また、TikTokのビュースルーアトリビューションのユーザー粒度データを取得することはエンドユーザー契約で認められていないため、2022-05-02以降のTikTokのビュースルーアトリビューションのユーザーのアトリビューション情報はすべて"TikTok Restricted"としてマークされます |
お使いのTwitterの統合ポイントが、Twitterのデバイス粒度のアトリビューションデータを受け取る資格を持っていることを確認してください Twitterのユーザー粒度のデータはアトリビューションから6か月後に消去されます。そのため、アトリビューションから6か月が経過すると、TwitterでアトリビューションされたユーザーはSingularシステムで "Organic"（オーガニック）として識別されます。また、Twitterのエンドユーザーには自分のデータをサードパーティから削除する権利があり、これらのユーザーのデータはユーザー粒度のデータには表示されませんが、集計データでは引き続き計算されます |