# 広告主向けの Reporting API > 広告主は Tapjoy Offerwall の Reporting API にアクセスし、詳細なデータの取得、アプリケーションのパフォーマンスの監視と評価、キャンペーンに関するより優れた分析情報獲得のためのレポートクエリの最適化を行うことができます。 パブリッシャーは Reporting API を使用して、オファーウォールで提供される広告のレポートデータを取得できます。 ## 前提条件##prerequisites [API を使用して認証する](./api-authentication.md) 必要があります。 * Reporting API を使用してキャンペーンを管理する方法については、[キャンペーンの管理](./campaign-management.md) を参照してください。 * Reporting API のエラー処理と制限事項については、[Reporting API のベストプラクティス](./reporting-api-best-practices.md) を参照してください。 ## 広告主レポート指標##advertiser-reporting-metrics Reporting API を使用して、収益、インプレッション数、コンバージョン数などの指標を含む、広告セットやマルチリワードイベントのパフォーマンスデータをリクエストできます。利用可能な広告主レポート指標はすべて、以下の表に列挙されています。 広告主には、以下の基本クエリからパフォーマンス指標の取得を開始することをお勧めします。 ```graphql query { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(timeRange: {from:"YYYY-MM-DDT00:00:00Z", until:"YYYY-MM-DDT00:00:00Z"}) { timestamps reports { impressions } } } } ``` | 広告主指標 | 説明 | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount | このイベントの入札額。 | | averageBid | 合計支出を合計コンバージョンで割った値。 | | callToActionClicks | 行動喚起が存在する場合に、ユーザーが行動喚起をクリックした回数。 | | clickToConversionTime | クリックからコンバージョンまでの時間データが複数の異なる方法でセグメント化されます。CTCT 指標は、毎日の最初の UTC 時間にだけ報告されることに注意してください。粒度 `HOURLY` を使用する場合、`00:00:00 UTC - 00:59:59 UTC` を表す時間のみが 0 以外の値になります。 | | conversions | 広告目標のコンバージョン数。 | | csConversions | 広告目標に対するカスタマーサービスのコンバージョン数。 | | csSpend | カスタマーサポートの総支出額。 | | ecpi | 合計支出を合計エンゲージメントで割った比率。 | | engagementInstalls | エンゲージメントから推定されたインストール数。 | | iaaRevenue | 選択した時間範囲内にオファーによって発生した合計広告収益。 | | iapRevenue | 選択した時間範囲内にオファーによって発生した合計 IAP 収益。 | | impressions | オファーウォールで広告がクリックされた回数。この指標はより正確には `impressions` ではなく `clicks` を表します。近くこのメトリックの名前を変更します。 | | offerwallAverageRank | 広告が配信されたオファーウォールの (加重) 平均位置。値は 1 から昇順で表示され、1 はオファーウォールの最上位の位置を表します。値 0 は、オファーが選択した期間にオファーウォールに表示されなかったことを表します。 | | offerwallImpressions | 広告がオファーウォールに表示された回数。広告が Offerwall に表示されても、ユーザーによって視聴されない (例えばユーザーが広告を見ることができる位置までスクロールしていない) ことがあります。広告主には、以下の `offerwallTrueImpressions` の使用をお勧めします。 | | offerwallTrueImpressions | オファーウォールでユーザーが広告を視聴した回数。各視聴は真のインプレッションとして登録されます。 | | returnOnAdSpend | 各日にインストールしたユーザーの広告費回収率データ。広告費回収率指標は、毎日の最初の UTC 時間にだけ報告されることに注意してください。 | | dayXRoas | インストールから `X` 日間の広告費回収率の合計。これは `dayXRoasRevenue` を `dayXRoasSpend` で割った値として計算されます。`dayXRoasRevenue` が 0 の場合、このフィールドも 0 になります。`X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` で使用できます。 | | dayXRoasAdRevenue | インストール後 `X` 日間にオファーをインストールしたユーザーから発生した合計広告収益。`X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` で使用できます。 | | dayXRoasEngagements | インストールから `X` 日間の合計ユーザーエンゲージメント数。`X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` で使用できます。 | | dayXRoasIapRevenue | インストールから `X` 日後に発生した、選択した期間にオファーをインストールしたユーザーからの合計 IAP 収益。`X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` で使用できます。 | | dayXRoasRevenue | インストールから `X` 日後に発生した、選択した期間にオファーをインストールしたユーザーからの収益合計額 (IAP + 広告収益)。これは `dayXRoasIapRevenue` に `dayXRoasAdRevenue` を加算した値として計算されます。`X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` で使用できます。 | | dayXRoasSpend | インストールから `X` 日間の広告主の合計支出額。`X = 0, 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90` で使用できます。 | | spend | 合計支出額。 | | totalRevenue | 選択した期間のオファーによって発生した収益合計額 (IAP + 広告収益)。これは `iaaRevenue` に `iapRevenue` を加算した値として計算されます。 | ダッシュボードで利用可能な追加の広告主指標 * コンバージョン率 (CVR) * 指示 CVR * コンバージョン数/インプレッション数 * クリックスルー率 (CTR) * *合計* 支出による ROAS (Reporting API は *コホート化* された支出による ROAS を返します) ## 指標のセグメント化##metric-segmentations クエリにセグメントフィールドを追加することで、API はイベント、パブリッシャーアプリケーション、国などセグメントごとのパフォーマンスデータを返すことができます。Reporting API は、以下の内訳でのセグメント化に対応しています。 * country * attributionSource * language * platform * id (パブリッシャーアプリ ID) * id (AdSet/オファー ID) * multiRewardEngagementEvent ### セグメント化の例##segmentation-examples #### 国、アトリビューションソース、言語別のセグメント##segment-by-country-attribution-source-and/or-language 以下のクエリは、特定の広告セットと期間について、国、アトリビューションソース、および言語でセグメント化されたコンバージョンデータを返します。 ```graphql title="Query" { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(timeRange: {from:"2024-08-01T00:00:00Z", until:"2024-08-01T11:59:59Z"}, timeIncrement:DAILY) { timestamps reports { country attributionSource language conversions } } } } ``` ```graphql title="Result" { "data": { "adSet": { "insights": { "timestamps": [ "2024-08-01T00:00:00Z" ], "reports": [ { "country":"FR", "attributionSource":"OTHER", "language":"RU", "conversions": [ 1 ] }, { "country":"FR", "attributionSource":"OTHER", "language":"FR", "conversions": [ 17 ] }, { "country":"CA", "attributionSource":"OTHER", "language":"EN", "conversions": [ 16 ] }, { "country":"AU", "attributionSource":"OTHER", "language":"EN", "conversions": [ 3 ] }, ] } } } } ``` #### プラットフォーム別のセグメント##segment-by-platform 以下のクエリは、最初の 2 つのキャンペーンのインプレッションデータをプラットフォーム別に返します。 ```graphql title="Query" { advertiser{ id campaigns(first: 2){ nodes{ insights{ reports{ impressions platform } } } } } } ``` ```graphql title="Result" { "data": { "advertiser": { "id":"00000000-0000-0000-0000-000000000000", "campaigns": { "nodes": [ { "insights": { "reports": [ { "impressions": [ 0 ], "platform": null } ] } }, { "insights": { "reports": [ { "impressions": [ 0 ], "platform": null } ] } } ] } } } } ``` #### パブリッシャーアプリ別のセグメント##segment-by-publisher-app 以下のクエリは、特定の広告セットのインプレッション数、コンバージョン数、支出額をパブリッシャーのアプリケーション別に返します。 ```graphql title="Query" query { adSet(id:"00000000-0000-0000-0000-000000000000") { ads { id insights(timePreset: TODAY) { reports { app { bundleId } impressions conversions spend } } } } } ``` ```graphql title="Result" { "data": { "adSet": { "ads": [ { "id":"10000000-0000-0000-0000-000000000000", "insights": { "reports": [ { "app": { "bundleId": "com.example.app", }, "impressions": [ 6147 ], "conversions": [ 24 ], "spend": [ 73000000 ] }, { "app": { "bundleId": "com.example.app2", }, "impressions": [ 4131 ], "conversions": [ 12 ], "spend": [ 73000000 ] }, { "app": null, "impressions": [ 5427 ], "conversions": [ 34 ], "spend": [ 73000000 ] } ] } }, { "id": "20000000-0000-0000-0000-000000000000", "insights": { "reports": [ { "app": { "bundleId": "com.example.app", }, "impressions": [ 6142 ], "conversions": [ 24 ], "spend": [ 73000000 ] }, { "app": { "bundleId": "com.example.app2", }, "impressions": [ 4111 ], "conversions": [ 12 ], "spend": [ 73000000 ] }, { "app": null, "impressions": [ 5227 ], "conversions": [ 30 ], "spend": [ 73000000 ] } ] } } ], "insights": { "reports": [ { "app": { "bundleId": "com.example.app", }, "impressions": [ 12550 ], "conversions": [ 49 ], "spend": [ 147000000 ] }, { "app": { "bundleId": "com.example.app2", }, "impressions": [ 8242 ], "conversions": [ 24 ], "spend": [ 146000000 ] }, { "app": null, "impressions": [ 10654 ], "conversions": [ 64 ], "spend": [ 146000000 ] } ] } } } } ``` #### 広告セットまたはキャンペーン別のセグメント##segment-by-ad-set-or-campaign 以下のクエリは、指定された時間範囲の最大 50 個のアクティブな広告セットのコンバージョンと支出を返します。 ```graphql title="Query" query { advertiser { adSets(first:50, configuredStatus:ACTIVE) { edges { node { id insights(timeRange: {from:"2024-11-15T00:00:00Z", until:"2024-11-16T00:00:00Z"}) { timestamps reports { conversions spend } } } } } } } ``` ```graphql title="Result" { "data": { "advertiser": { "adSets": { "edges": [ { "node": { "id":"00000000-0000-0000-0000-000000000000", "insights": { "timestamps": [ "2024-11-15T00:00:00Z" ], "reports": [ { "impressions": [ 13550 ], "conversions": [ 53 ], "spend": [ 159000000 ] } ] } } }, { "node": { "id":"00000000-0000-0000-0000-000000000001", "insights": { "timestamps": [ "2024-11-15T00:00:00Z" ], "reports": [ { "impressions": [ 1220 ], "conversions": [ 8 ], "spend": [ 12300000 ] } ] } } } ] } } } } ``` #### マルチリワードエンゲージメントイベント別のセグメント##segment-by-multi-reward-engagement-event 以下のクエリは、マルチリワードエンゲージメントイベントによってセグメント化された、特定の広告セットのコンバージョンとDay-0のROASを返します。 ```graphql title="Query" { adSet(id:"00000000-0000-0000-0000-000000000000") { id insights(timeRange: {from:"2024-11-15T00:00:00Z", until:"2024-11-15T11:59:59Z"}, timeIncrement:DAILY) { timestamps reports { conversions returnOnAdSpend { day0Roas } multiRewardEngagementEvent { eventName } } } } } ``` ```graphql title="Result" { "data": { "adSet": { "id":"00000000-0000-0000-0000-000000000000", "insights": { "timestamps": [ "2024-11-15T00:00:00Z" ], "reports": [ { "conversions": [ 10 ], "returnOnAdSpend": { "day0Roas": [ 0 ] }, "multiRewardEngagementEvent": { "eventName":"Purchase=#" } }, { "conversions": [ 15 ], "returnOnAdSpend": { "day0Roas": [ 0 ] }, "multiRewardEngagementEvent": { "eventName":"LEVEL_#" } } ] } } } } ``` ## フィルタリング機能##filtering-capabilities クエリにフィルターを追加すると、API は指定されたソースからのみパフォーマンス指標を返します。Reporting API は以下のフィルタリング機能に対応しています。 * adSet (単一の広告セット) * adSets (複数の広告セット) * appIds (パブリッシャーアプリ) * configuredStatus (*ACTIVE*、*ARCHIVED*、または *PAUSED*) * countries * timePreset * timeRange ### フィルタリングの例##filtering-examples #### 広告セットによるフィルター##filter-by-ad-set これにより、結果が 1 つの *広告セット* に制限されます。 ```graphql title="GraphQL" query { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(timeRange: {from:"2024-08-06T00:00:00Z", until:"2024-08-07T00:00:00Z"}) { timestamps reports { impressions conversions spend offerwallAverageRank } } } } ``` #### 複数の広告セットによるフィルター##filter-for-multiple-ad-sets これにより、結果が *最初* または *最後* の x 個の広告セットに制限されます。 ```graphql title="GraphQL" query { advertiser { adSets(first:2) { edges { node { insights(timePreset:TODAY) { reports { conversions } } } } } } } ``` #### パブリッシャーアプリによるフィルター##filter-by-publisher-app 結果を指定したパブリッシャーアプリ ID に制限します ```graphql title="GraphQL" query { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(filter:{appIds: ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]}) { timestamps reports { conversions } } } } ``` #### 設定状態によるフィルター##filter-by-configured-status これにより、結果が指定された状態の広告セット/キャンペーンに制限されます。 **オプション**: `ACTIVE`、`ARCHIVED`、または `PAUSED` ```graphql title="GraphQL" query { advertiser { adSets(first:2, configuredStatus:ACTIVE) { edges { node { insights(timePreset:TODAY) { reports { conversions } } } } } } } ``` #### 国によるフィルター##filter-by-country これにより、結果が指定された国に制限されます ```graphql title="GraphQL" query { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(filter:{countries: [JP, US]}) { timestamps reports { conversions } } } } ``` #### プリセット期間によるフィルター##filter-by-a-preset-timeframe これにより、結果がプリセットされた期間に制限されます。これは相対的な時間範囲であり、クエリの実行時間によって結果が異なります。 **オプション**: `LAST 30D`、`LAST WEEK`、`TODAY`、`YESTERDAY`。 > **Note:** > > データ集計のレベルを定義するには、**timeIncrement** を組み込みます。**timeIncrement** は *DAILY*、*HOURLY*、*MONTHLY* の値を取ることができます。**timeIncrement** は任意のパラメーターで、デフォルトは *ALL* です。 ```graphql title="GraphQL" query { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(timePreset:LAST_30D, timeIncrement:DAILY) { reports { impressions } } } } ``` #### 絶対時間範囲によるフィルター##filter-by-an-absolute-time-range これにより、結果が指定された絶対時間範囲に制限されます。 最大範囲は 3 か月で、サポートされる最も古い日付は過去 2 年間です。 > **Note:** > > データ集計のレベルを定義するには、**timeIncrement** を組み込みます。**timeIncrement** は *DAILY*、*HOURLY*、*MONTHLY* の値を取ることができます。**timeIncrement** は任意のパラメーターで、デフォルトは *ALL* です。 ```graphql title="GraphQL" query { adSet(id:"00000000-0000-0000-0000-000000000000") { insights(timeRange: {from:"2024-11-15T00:00:00Z", until:"2024-11-17T00:00:00Z"}, timeIncrement:DAILY) { reports { impressions } } } } ``` ## 非推奨のディメンション##deprecated-dimensions 以下の古いディメンションは、2025 年 2 月 3 日に Reporting API から削除されました。API クエリが、以下の **太字** でリストされているディメンションを参照していないことを確認してください。これにより、Tapjoy のオファーウォールからデータを取得するときのエラーを回避できます。 * Enums > TargetConnectionType > **MOBILE** * Enums > TargetDeviceType > **WINDOWS**