アプリ ユーザー エージェント
スパム対策の幅広い取り組みの一環として、Google はアプリユーザーに代わってアナリティクス/広告プロダクトから送信される User-Agent ヘッダーの標準仕様を作成しました。アプリのユーザー エージェントは、次の仕様に従ってネイティブ コードから導出できます。
name version (os_and_version; locale; device; build; Proxy)
これらのフィールドの定義は次のとおりです。
| ユーザー エージェント コンポーネント | |
|---|---|
| name | 分析/広告プロダクトの名前。（ ユーザー エージェントがクライアント側で作成されている場合、 Android// Specified by API consumer. iOS// Specified by API consumer. |
| version | 分析/広告プロダクトのバージョン。（ Android// Specified by API consumer. iOS// Specified by API consumer. |
| os_and_version | アプリが実行されているオペレーティング システムとオペレーティング システムのバージョン。（ Android
String osAndVersion =
"Android " + Build.VERSION.RELEASE;
iOS
UIDevice *uid =
[UIDevice currentDevice];
NSString *osAndVersion =
[NSString
stringWithFormat:@"%@ %@",
[uid systemName],
[uid systemVersion]];
|
| locale | デバイスの IETF ロケールタグ。2 文字の言語と国コードをアンダースコアで区切って使用します。（ AndroidString locale = Locale.getDefault(); iOS
NSString *locale =
[[NSLocale currentLocale]
localeIdentifier]
|
| device | 分析/広告プロダクトを実行している実機の名前。（ AndroidString device = Build.MODEL; iOS
@import Darwin.sys.sysctl;
NSString *device(void) {
size_t bufferSize = 64;
NSMutableData *buffer =
[[NSMutableData alloc]
initWithLength:bufferSize];
int status =
sysctlbyname("hw.machine",
buffer.mutableBytes,
&bufferSize, NULL, 0);
if (status != 0) {
return nil;
}
return [[NSString alloc]
initWithCString:buffer.mutableBytes
encoding:NSUTF8StringEncoding];
}
|
| build | 「Build/"」の後にオペレーティング システムのビルド番号を付加します。（ AndroidString build = "Build/" + Build.ID; iOS
@import Darwin.sys.sysctl;
NSString *build(void) {
size_t bufferSize = 64;
NSMutableData *buffer =
[[NSMutableData alloc]
initWithLength:bufferSize];
int status =
sysctlbyname("kern.osversion",
buffer.mutableBytes,
&bufferSize, NULL, 0);
if (status != 0) {
return nil;
}
return [[NSString alloc]
initWithCString:buffer.mutableBytes
encoding:NSUTF8StringEncoding];
}
|
アプリのユーザー エージェント サーバー側を作成するときは、アプリ ユーザー エージェントの末尾にのみ ; Proxy を含めます。アプリのユーザー エージェントがクライアント側ですべて構成されている場合は、; Proxy を除外します。したがって、アプリのユーザー エージェントは次のようなものになります。
- Android:
AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M; Proxy) - iOS:
AdMob/7.10.1 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
コンバージョン トラッキング リクエスト
コンバージョン トラッキング リクエストは、コンバージョンとしてトラッキングするアプリや、リマーケティング リストの入力に使用するアプリイベントを Google 広告に通知し、このイベントの前に発生したクリックに関するメタデータを取得することを目的としています。
API 呼び出しはすべて www.googleadservices.com ドメインに対して行われます。コンバージョン リクエストは、HTTPS 経由の POST リクエストです。ここで、
/pagead/conversion/app/versionは version がコンバージョン トラッキング API の目的のバージョンです。現在、有効なバージョンは
1.0 のみです。
標準のアプリ コンバージョン リクエストには次のパラメータが含まれます。
| コンバージョン トラッキング リクエスト | |
|---|---|
dev_token |
必須 ロケーション: クエリ API コンシューマに発行される一意の静的開発者トークン。 Z_eErE4DkvcKjDM1OVE4c4 |
link_id |
必須 ロケーション: クエリ API コンシューマの開発者トークンを特定のアプリにバインドするリンク識別子。 31FF8D67E5BB5DD5029DCC2734C2F884 |
app_event_type |
必須 ロケーション: クエリ 発生したアプリイベントの名前。このフィールドは列挙値であり、次の値のみを受け入れます。 • first_open • session_start • in_app_purchase • view_item_list • view_item • view_search_results • add_to_cart • ecommerce_purchase • custom インストールのアトリビューションを行うには、常に |
app_event_name |
特定の条件下で必須 ロケーション: クエリ
level_achieved Level Achieved このフィールドに |
app_event_data |
任意 場所: 本文 追加のリッチイベントデータを、文字列キーを値にマッピングするシンプルな JSON オブジェクトとして転送します。有効な値は、文字列と文字列の配列です。
{"level": 5, "attempts": 20}
|
rdid |
必須 ロケーション: クエリ 未加工のデバイス ID を表す有効な UUID 文字列。 f10e1de2-e237-4f50-b6aa-843c45cc63d6 ATT で同意していないユーザーのデバイス ID など、デバイス ID がない場合は、すべてゼロに設定します。 00000000-0000-0000-0000-000000000000 |
id_type |
必須 ロケーション: クエリ
Androidadvertisingid iOSidfa |
lat |
必須 ロケーション: クエリ デバイスの広告トラッキング制限ステータス。
|
app_version |
必須 ロケーション: クエリ アプリの現行バージョン。これは、次のように標準化されます。 AndroidpackageManager.getPackageInfo(packageName(), PackageManager.GET_META_DATA).versionName iOS[[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"] 1.2.4 |
os_version |
必須 ロケーション: クエリ アプリのホスト OS の現在のバージョン。次のように標準化する必要があります。 Androidandroid.os.Build.VERSION.RELEASE iOS[[UIDevice currentDevice] systemVersion] |
sdk_version |
必須 ロケーション: クエリ イベントを測定した SDK のバージョン。これは主にデバッグに使用されるため、SDK リリースで公開されるリリース バージョンを正確に反映する必要があります。アプリで SDK を使用しない場合は、 1.9.5r6 |
timestamp |
必須 ロケーション: クエリ コンバージョン イベントが発生した UNIX タイムスタンプ（最大マイクロ秒単位の秒単位）。 1432681913.123456 |
value |
任意 ロケーション: クエリ イベントの金銭的価値（ある場合）。常に小数点を使用して、機械可読形式の浮動小数点値としてフォーマットし、値の整数部と小数部を区切る必要があります。 1.99 |
currency_code |
特定の条件下で必須 ロケーション: クエリ
USD |
gclid |
特定の条件下で必須 ロケーション: クエリ アプリが開いたディープリンク URL の Cj0KEQjw0dy4BRCuuL_e5M |
market_referrer_gclid |
特定の条件下で必須 ロケーション: クエリ Play Install Referrer API を使用して install_referrer の値から取得された、ディープリンク URL の BX3QojHp4mY5MrJtFM_d1u |
gclid_only_request |
特定の条件下で必須 ロケーション: クエリ rdid（広告 ID）が 1 |
gbraid |
特定の条件下で必須 ロケーション: クエリ アプリが最後に開いたディープリンク URL を介して送信された ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O |
app_open_source |
特定の条件下で必須 ロケーション: クエリ 広告クリックのディープリンクまたはオーガニック アプリのセッションを識別する値。 ad_click or organic |
User-Agent |
必須 場所: ヘッダー 前のセクションで定義したアプリユーザー エージェント。 AdMob/7.10.1 (Android 6.0; en_US; SM-G900F; Build/MMB29M) |
X-Forwarded-For |
必須 場所: ヘッダー イベントが測定されたデバイスのパブリック IPv4 または IPv6 アドレス。 216.58.194.174 |
すべてのリクエストは HTTPS 経由で送信する必要があります。HTTP 経由で受信した ping は拒否されます。
リクエスト本文が空の場合（app_event_data ペイロードにリッチイベント データが渡されない場合は）、リクエストに Content-Length: 0 ヘッダーを明示的に設定する必要があります。
リクエストの例
カスタム以外のイベントタイプと収益の情報を含む有効なコンバージョン トラッキング リクエストの例:
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=in_app_purchase
&rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
&id_type=idfa
&lat=0
&app_version=1.2.4
&os_version=9.3.2
&sdk_version=1.9.5r6
×tamp=1432681913.123456
&value=1.99
¤cy_code=USD
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
{"app_event_data":{"item_id":["Crayons","Markers"]}}
カスタム以外のイベント タイプと収益情報（rdid（広告 ID）が利用できない）を含む有効なコンバージョン トラッキング リクエストの例を次に示します。
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=in_app_purchase
&rdid=00000000-0000-0000-0000-000000000000
&id_type=advertisingid
&lat=1
&app_version=1.2.4
&os_version=9.3.2
&sdk_version=1.9.5r6
×tamp=1432681913.123456
&value=1.99
¤cy_code=USD
&market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
&gclid=Cj0KEQjw0dy4BRCuuL_e5M
&gclid_only_request=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; Android,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
{"app_event_data":{"item_id":["Crayons","Markers"]}}
有効なセッション開始リクエストの例を次に示します。
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=session_start
&rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
&id_type=idfa
&lat=0
&app_version=1.2.4
&os_version=9.3.2
&sdk_version=1.9.5r6
×tamp=1432681913.123456
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
ディープリンク example://product/123?gclid=Cj0KEQjw0dy4BRCuuL_e5M から開始されたセッションに有効なセッション開始再アトリビューション リクエストの例を次に示します。
POST /pagead/conversion/app/1.0
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=session_start
&rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
&id_type=idfa
&lat=0
&app_version=1.2.4
&os_version=9.3.2
&sdk_version=1.9.5r6
×tamp=1432681913.123456
&gclid=Cj0KEQjw0dy4BRCuuL_e5M
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
イベントデータのエンコード
app_event_data 本体パラメータについては、プリミティブ データ型について以下の規則を使用してください。
浮動小数点数
- アプリのローカライズとは別に、ドット文字を小数点記号として使用する
- 金銭的価値を表すには、2 桁の小数点精度を使用します（例: 2.99）。
- 指数表記（例: 2E+9）を使用しない
- 数字の区切りにカンマ文字を使用しないでください（例: 1,000,000）。
- 有効な例:
-0.52.991000000.123
整数
- 小数点以下を含まない整数値のみを送信
- 数字を区切るにはカンマを使用しないでください（例: 1,000,000）。
- 有効な例:
1000-110
日付
- 日付形式: yyyy-mm-dd
yyyy= 4 桁の年（例: 2016）mm= 2 桁の月（例: 9 月の場合は 09）dd= 2 桁の日（例: 月の 23 日の 23）
- 常に上で指定された桁数を送信します。たとえば、月の 5 日目の dd の値を送信する場合は、
05を送信します。 - 有効な例:
"2016-09-23""1990-12-31"
- 日付形式: yyyy-mm-dd
Timestamp（タイムスタンプ）
- 時刻の形式: 最大 マイクロ秒の精度で UTC タイムゾーンで定義された Unix/エポック タイムスタンプ
- 有効な例:
1478713087: 2016 年 11 月 9 日（水）17:38:07 GMT1073513982.123000（水）、2004 年 1 月 7 日 22:19:42.123 GMT
配列
- プリミティブ値（文字列、数値、ブール値）の配列のみを送信する
- 有効な例:
[123, 456, 789]["abc"]
コンバージョン トラッキングのレスポンス
コンバージョン トラッキングのレスポンスの形式は次のとおりです。
{
"ad_events": [<ad event objects>],
"errors": [<error strings>],
"attributed": true|false
}
ad_events 配列と errors 配列は空でもかまいません。
エラーは、機械可読形式のエラーコード（invalid_timestamp など）になると予想されます。
広告イベントはアプリ アトリビューションの中核となるオブジェクトで、以下のプロパティが含まれます。
| コンバージョン トラッキングのレスポンス | |
|---|---|
ad_event_id |
常に存在 文字列
Q2owS0VRancwZHk0QlJDdXVMX2U1TQ |
conversion_metric |
常に存在 文字列 アトリビューションに使用されるコンバージョン指標。最初は 1 つのコンバージョン指標がサポートされます。 conversion |
timestamp |
常に存在 数値 広告イベントが発生した UNIX タイムスタンプ（秒単位で最大マイクロ秒単位）。この値は、ラストクリック アトリビューションに使用します。 1432681913.123456 |
campaign_type |
常に存在 文字列 このフィールドは、広告イベントが発生したキャンペーンのタイプを示します。使用できる値は次のとおりです。 ACI ACE Search Display Video Shopping Hotel Performance_Max Other ACI は、「アプリ インストール キャンペーン」の略です。ACE は「App Campaigns for Engagement」の略です。 |
campaign_id |
常に存在 数値 広告イベントが発生したキャンペーンの数値 ID。この値は一意であることが保証されています。 123456789 |
campaign_name |
常に存在 文字列 広告イベントが発生したキャンペーンの、広告主様が定義したキャンペーン名です。この値は一意になるとは限りません。 Occasional Gamers (Video) |
ad_type |
常に存在 文字列 広告イベントにつながった広告のタイプ。この値は、次のようにさまざまなタイプの広告枠を区別するために使用されます。 アプリのプロモーションClickToDownloadアプリ エンゲージメント AppDeepLinkアプリ エンゲージメント - インストールと続行のフロー AppDeepLinkContinue他の値のキャッチオール Unknown |
external_customer_id |
常に存在 数値 広告イベントを生成したキャンペーンを所有する広告主の広告主 ID。この値を使用して、Google 広告アカウントを区別できます。 123456789 |
location |
常に存在 数値 広告イベントの地理的位置に基づく地域 ID コードです。地域コードの意味については、Google Ads API のリファレンスをご覧ください。 |
network_type |
常に存在 文字列 このフィールドは、広告イベントが発生した Google 広告の広告ネットワークを識別します。使用できる値は次のとおりです。 Search Display YouTube |
network_subtype |
文字列 このフィールドは、広告イベントが発生した Google 広告ネットワークの「サブタイプ」を表します。指定できる値は、プライマリ ネットワークの種類によって異なります。 検索通常の Google 検索GoogleSearchGoogle 検索パートナー SearchPartners Displayモバイルウェブ パブリッシャーmGDNアプリ パブリッシャー Google AdMob YouTubeYouTube 動画ネットワークYouTubeVideosYouTube 検索ネットワーク YouTubeSearch動画パートナー VideoPartners |
video_id |
文字列 広告イベントに関連付けられた YouTube 動画 ID。 dQw4w9WgXcQ |
keyword |
文字列 広告イベントに関連付けられた検索キーワード。 +food +delivery |
match_type |
文字列 検索キーワードのマッチタイプ。 完全一致eフレーズ一致 p部分一致 b |
placement |
文字列 広告イベントに関連付けられているプレースメントです。 mobileapp::1-343200656 |
ad_group_id |
常に存在 数値 広告イベントで生成された広告グループの数値 ID。この値は一意であることが保証されています。 123456789 |
ad_group_name |
文字列 広告イベントが発生した広告グループの広告主定義の広告グループ名。この値は一意になるとは限りません。 My App AdGroup |
creative_id |
数値 広告イベントが発生したクリエイティブ広告ユニットの数値 ID。この値は一意であることが保証されています。 123456789 |
interaction_type |
この項目は常にエンゲージメントです。 文字列 |
レスポンス例
リクエストにエラーが含まれている場合のコンバージョン トラッキング レスポンスの例を次に示します。
{
"ad_events": [],
"errors": ["INVALID_CURRENCY_CODE"],
"attributed": false
}
否定的なコンバージョン トラッキング レスポンスの例を次に示します。
{
"ad_events": [],
"errors": [],
"attributed": false
}
コンバージョン トラッキング リクエストは、すべてのコンバージョン トラッキング リクエストに対して返されます。
ユニバーサル アプリ キャンペーンの肯定的なコンバージョン トラッキング レスポンスの例を次に示します。
{
"ad_events": [{
"ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
"conversion_metric": "conversion",
"interaction_type": "engagement",
"campaign_type": "ACI",
"campaign_id": 123456789,
"campaign_name": "My App Campaign",
"ad_type": "ClickToDownload",
"external_customer_id": 123456789,
"location": 21144,
"network_type": "Search",
"network_subtype": "GoogleSearch",
"video_id": null,
"keyword": null,
"match_type": null,
"placement": null,
"ad_group_id": null,
"ad_group_name": "",
"creative_id": null,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
検索キャンペーンの肯定的なコンバージョン トラッキング レスポンスの例を次に示します。
{
"ad_events": [{
"ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
"conversion_metric": "conversion",
"interaction_type": "engagement",
"campaign_type": "Search",
"campaign_id": 123456789,
"campaign_name": "My App Campaign",
"ad_type": "ClickToDownload",
"external_customer_id": 123456789,
"location": 21144,
"network_type": "Search",
"network_subtype": "GoogleSearch",
"video_id": null,
"keyword": "+space +birds",
"match_type": "b",
"placement": null,
"ad_group_id": 123456789,
"ad_group_name": "My App AdGroup",
"creative_id": 123456789,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
ディスプレイ キャンペーンの肯定的なコンバージョン トラッキング レスポンスの例:
{
"ad_events": [{
"ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
"conversion_metric": "conversion",
"interaction_type": "engagement",
"campaign_type": "Display",
"campaign_id": 123456789,
"campaign_name": "My App Campaign",
"ad_type": "ClickToDownload",
"external_customer_id": 123456789,
"location": 21144,
"network_type": "Display",
"network_subtype": "mGDN",
"video_id": null,
"keyword": null,
"match_type": null,
"placement": "mobile-app::2-343200656",
"ad_group_id": 123456789,
"ad_group_name": "My App AdGroup",
"creative_id": 123456789,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
YouTube キャンペーンの肯定的なコンバージョン トラッキング レスポンスの例を次に示します。
{
"ad_events": [{
"ad_event_id": "Q2owS0VRancwZHk0QlJDdXVMX2U1TQ",
"conversion_metric": "conversion",
"interaction_type": "engagement",
"campaign_type": "Video",
"campaign_id": 123456789,
"campaign_name": "My App Campaign",
"ad_type": "ClickToDownload",
"external_customer_id": 123456789,
"location": 21144,
"network_type": "YouTube",
"network_subtype": "YouTubeVideos",
"video_id": "dQw4w9WgXcQ",
"keyword": null,
"match_type": null,
"placement": null,
"ad_group_id": 123456789,
"ad_group_name": "My App AdGroup",
"creative_id": 123456789,
"timestamp": 1432681913.123456
}],
"errors": [],
"attributed": true
}
クロスネットワーク アトリビューション リクエスト
Google 広告がコンバージョン トラッキング リクエストに肯定的な応答を返す場合、API ユーザーはラストクリックを特定した後に、クロスネットワークのアトリビューションに関する決定を Google 広告に通知する必要があります。
クロスネットワーク アトリビューション リクエストは最初のコンバージョン トラッキング リクエストと同じですが、リクエストパスは次のようになります。
/pagead/conversion/app/1.0/cross_network
2 つの必須パラメータを追加しました。
| クロスネットワーク アトリビューション リクエスト | |
|---|---|
ad_event_id |
必須 ロケーション: クエリ 前のリクエストでアトリビューションに関連付けられた広告イベントの |
attributed |
必須 ロケーション: クエリ API コンシューマがコンバージョンへの貢献度を Google 広告に与えたかどうか。 |
有効なクロスネットワーク アトリビューション リクエストの例:
POST /pagead/conversion/app/1.0/cross_network
?dev_token=Z_eErE4DkvcKjDM1OVE4c4
&link_id=31FF8D67E5BB5DD5029DCC2734C2F884
&app_event_type=custom
&app_event_name=level_achieved
&rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
&id_type=idfa
&lat=0
&app_version=1.2.4
&os_version=9.3.2
&sdk_version=1.9.5r6
×tamp=1432681913.123456
&value=1.99
¤cy_code=USD
&ad_event_id=Q2owS0VRancwZHk0QlJDdXVMX2U1TQ
&attributed=1
Host: www.googleadservices.com
User-Agent: MyAnalyticsCompany/1.0.0 (iOS 10.0.2; en_US; iPhone9,1; Build/13D15; Proxy)
X-Forwarded-For: 216.58.194.174
Content-Type: application/json; charset=utf-8
有効なクロスネットワーク アトリビューション リクエストでは、常にレスポンス本文のない一般的な 200 のレスポンスが返されます。