はじめに

アナリティクスメトリックは、パートナーや広告主がTwitterでプロモーションしているコンテンツのパフォーマンスを理解するのに役立ちます。これには、インプレッション数、クリック数、動画再生数、利用金額などの情報が含まれます。さらに、パートナーと広告主は、リーチするオーディエンスのさまざまなセグメントに関する詳細なメトリックを得ることができます。

広告APIは、キャンペーンの詳細なパフォーマンスメトリックを取得する方法として、同期と非同期の2つの方法をサポートしています。同期アナリティクス呼び出しでは、リクエストしたメトリックが応答で返されます。非同期アナリティクスエンドポイントでは、関連する「ジョブ」による処理の終了後に、ダウンロード可能な結果ファイルでリクエストしたメトリックを利用できます。同期エンドポイントは、短い時間範囲をサポートし、リアルタイムのキャンペーンの最適化に理想的です。非同期エンドポイントは、それより長い時間範囲をサポートし、より多くのデータを取得することを目的としているため、レポートや履歴バックフィルの生成に理想的です。

詳細

同期と非同期

次の表に、同期アナリティクスエンドポイントと非同期アナリティクスエンドポイントの違いをまとめます。この情報は、開発者が使用するエンドポイントセットを選択する際に役立ちます。

*特定の時点で処理状態にある可能性のあるジョブの最大数を表します。
**ジョブによる処理が正常に終了すると、URLが返されます。こちらから圧縮（gzip）された結果ファイルをダウンロードできます。

以上を除くと、エンドポイントによって提供される機能は同じです。

ユースケース

アナリティクスの主なユースケースには、次の3つがあります。

1. リアルタイムの最適化: パフォーマンスメトリックを使用してアクティブなキャンペーンを更新します
2. 同期: 定期的にバックグラウンド同期を実行します
3. 新しいアカウントのオンボーディング: 履歴データをバックフィルします

同期アナリティクスエンドポイントをリアルタイムの最適化に使用すると、直近5～15分以内のメトリックの変更に基づいてキャンペーンを更新できます。いずれのエンドポイントもアナリティクス同期に使用できます。必要な時間範囲とセグメント化が必要かどうかによって、使用するエンドポイントが決まります。新規アカウントのオンボーディングは、非同期アナリティクスエンドポイントのみを使用して行います（同期アナリティクスエンドポイントは、大量のデータの取得には使用しないでください）。

非同期エンドポイントアナリティクスを使用すると、メトリックがバックエンドプロセスと同期している場合に、管理画面や他のUIの要素を作成できます。使用する実装では、ユーザーインターフェイスリクエストの処理に非同期アナリティクスエンドポイント呼び出しを使用しないでください。

リクエストオプション

アナリティクスリクエストは広告アカウントを対象としているため、リソースパスにはアカウントIDが必要です。クエリパラメーターにリクエストオプションを指定した例を次に示します。次のタイプの値が必要です。

• エンティティ: アナリティクスをリクエストするエンティティのタイプとエンティティID（最大20件）
• 時間範囲: 開始時間と終了時間（ISO 8601で表したもの）
  • 注: これらは時間の単位で表す必要があります
• メトリックグループ: 1つ以上の関連するメトリックのセット（各メトリックグループのメトリックのリストについては、「メトリックとセグメント化」を参照してください）
• 詳細度: メトリックを返す集計レベルを指定します
• 配置: TwitterまたはTwitter以外で配信された広告のメトリックを取得するかどうかを決定します
  • 注: 指定できる配置値はリクエストにつき1つのみです

時間範囲を指定するには、start_timeとend_timeのリクエストパラメーターを使用します。これらの値は、次の方法で指定した詳細度に合わせる必要があります。

1. TOTAL: 時間範囲を指定します（エンドポイントの制限内）
2. DAY: 開始時間と終了時間の値は、アカウントのタイムゾーンの午前0時に設定する必要があります
3. HOUR: 時間範囲を指定します（エンドポイントの制限内）

終了時間は両端を含みません。たとえば、start_time=2019-01-01T00:00:00Zとend_time=2019-01-02T00:00:00Zを使用したリクエストであれば、時間範囲が24時間のみとなるため、2日分ではなく1日分に相当するアナリティクスメトリックが返されます。

セグメント化

セグメント化は、非同期アナリティクスエンドポイントを介してのみ利用可能です。セグメント化を使用すると、パートナーと広告主は、メトリックを細分化した特定のターゲティング値を取得できます。セグメント化されたメトリックをリクエストするには、segmentation_typeリクエストパラメーターを使用します。セグメント化のオプションの詳細については、「メトリックとセグメント化」を参照してください。

よくある質問

広告API番号がTwitter広告UIに表示されるものと一致しないのはなぜですか？

• 両方の配置（ALL_ON_TWITTERとPUBLISHER_NETWORK）のデータをリクエストしたことを確認してください
• 終了時間は、広告APIでは両端を含まず、広告UIでは両端を含みます

データをリクエストした時期に応じて数字が変わるのはなぜですか？

• レポート用メトリックは利用可能になり次第取得でき、このメトリックはほぼリアルタイムで利用できます。ただし、こうした早期の結果は推測値であるため、変わることが予想されます。利用金額データを除くすべてのメトリックは24時間後に確定します。
• 利用金額メトリックは通常イベント後3日以内に確定します。ただし、請求データの処理（スパムのフィルタリングなど）にはイベント日から最大で14日間かかります。

特定の期間に対してリクエストするエンティティIDはどのようにして決定すればよいですか？

• アクティブエンティティエンドポイントを使用してください

アナリティクスの応答nullにすべての値が表示されるのはなぜですか？

• リクエスト期間中にキャンペーンが配信されなかった可能性があります
• アクティブエンティティエンドポイントを使用して、どのエンティティでどの期間のアナリティクスを取得するのか決めてください

APIにはnull値が表示され、UIには「0」が表示されるのはなぜですか？

• UIにはこれらの値を「0」と表示しますが、値は同じものです

Twitterタイムラインのように、詳細度の配置に関連するメトリックをリクエストするにはどうすればよいですか？

• アナリティクスでは、ALL_ON_TWITTERとPUBLISHER_NETWORK（例: Twitterオーディエンスプラットフォーム）の2つの配置値のみをサポートしています

削除済みまたは一時停止中のエンティティのメトリックを取得できますか？

• はい。エンティティのステータスはアナリティクスメトリックの利用可能性に影響しません。

セグメント化された値とセグメント化されていない値が一致しないのはなぜですか？

• すべてのセグメント化されたデータがセグメント化されていないデータにまとめられるわけではありません。これは、情報の取得方法が影響しています。

複数のディメンションでセグメント化されたデータをリクエストすることはできますか？

• 複数セグメント化はサポートされていません