アナリティクス

アクティブエンティティ

はじめに

アクティブエンティティエンドポイントは、アナリティクスのリクエスト先となるキャンペーンについての情報を提供することから、Twitterの同期アナリティクスおよび非同期アナリティクスエンドポイントと組み合わせて使用できます。これは、広告エンティティに関する詳細とそれらのメトリックが変更された時間を返すことによって行われます。このエンドポイントを使用すると、コードの作成やアナリティクスの取得ロジックを大幅に簡素化できます。

このガイドには、エンドポイントとそのデータソースに関する情報とコンテキストが含まれています。また、アクティブエンティティをアナリティクスエンドポイントと組み合わせて使用​​する方法の理解に役立つ、使用上のガイドラインや一連のリクエスト例も提供されます。概要セクションでは、推奨されるアプローチについての概略を説明します。

データ

広告エンティティのメトリックが変更されるたびに、その変更に関する情報が記録されます。1時間ごとのバケットに格納される、これらの変更イベントには、エンティティに関する詳細のほか、変更が適用される時間が含まれます。変更イベントは、それらが記録される時間と常に一致するわけではないため、変更が適用される時間に関する情報が必要になります。請求の調整がこれに該当しますが、ほかにもこの情報が必要となる場合があります。

エンドポイント

リクエスト

アクティブエンティティリクエストの範囲は広告アカウントによって決まり、3つの必須クエリパラメーターとしてentity、start_time、end_timeがあります。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z"

以下のentity値がサポートされています: CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_ACCOUNT、PROMOTED_TWEET。これには、Twitterのアナリティクスエンドポイントがサポートするエンティティタイプが反映されます。

start_timeとend_timeの値は、ISO 8601で表し、クエリ対象の1時間ごとのバケットを指定する必要があります。これらは時間の単位で表す必要があります。

このエンドポイントでは、3つのオプションパラメーターfunding_instrument_ids、campaign_ids、line_item_idsもサポートされており、結果を絞り込むために使用できます。これらのオプションは広告階層のすべてのレベルで機能し、任意のentityタイプを指定して使用できます。

応答

上記のリクエストに対するアクティブエンティティの応答は、次のとおりです。

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "entity": "PROMOTED_TWEET",
      "start_time": "2019-03-05T00:00:00Z",
      "end_time": "2019-03-06T00:00:00Z"
    }
  },
  "data": [
    {
      "entity_id": "2r0wxw",
      "activity_start_time": "2019-03-04T20:55:20Z",
      "activity_end_time": "2019-03-05T03:43:56Z",
      "placements": [
        "ALL_ON_TWITTER"
      ]
    },
    {
      "entity_id": "2r30fn",
      "activity_start_time": "2019-03-05T08:11:08Z",
      "activity_end_time": "2019-03-05T14:40:59Z",
      "placements": [
        "ALL_ON_TWITTER",
        "PUBLISHER_NETWORK"
      ]
    }
  ]
}

data配列には、後続のアナリティクスリクエストに含める必要がある、すべてのエンティティのオブジェクトが含まれます。このセット以外のIDには、アナリティクスをリクエストできません。

各オブジェクトには、entity_id、activity_start_time、activity_end_time、placementsの4つのフィールドがあります。アクティビティの開始時間と終了時間は、関連するエンティティの変更イベントが適用される時間範囲を表します。したがって、後続のアナリティクスリクエストで指定する日付が決まります。placements配列には、ALL_ON_TWITTER、PUBLISHER_NETWORKのいずれか、またはその両方を含められます。特定のエンティティIDに対してどの配置をリクエストするかを示します。

使用方法

アクティブエンティティエンドポイントは、アナリティクスリクエストの使用方法を指示する必要があります。次の使用方法に関するガイドラインは、アナリティクスの同期をサポートするためのものです。同期をサポートすることによって、パートナーはデータストアをTwitterと同期できます。つまり、定期的にバックグラウンド同期を実行する方法について説明しています。

開発者は、次の2点を決めておく必要があります。

  1. アクティブエンティティについての情報をリクエストする頻度、つまりアナリティクスを取得する頻度。
  2. アクティビティの開始時間と終了時間を使用して、アナリティクスリクエストのstart_timeとend_timeの値を決定するための方法。

これらについては、次の概要の後にある2つのサブセクションでそれぞれ詳しく説明します。

概要

アナリティクスリクエストの使用方法を指定するには、アクティブエンティティエンドポイントを次のように使用します。アクティブエンティティについての情報をリクエストする頻度、つまりアナリティクスを取得する頻度を決定した後に、この手順に従ってください。

  1. アクティブエンティティリクエストを行います。
  2. 応答を配置ごとに分割します。ALL_ON_TWITTERのグループと、PUBLISHER_NETWORKのグループになります。
  3. 配置グループごとに、次の操作を実行します。
    1. エンティティIDを抽出します。
    2. アナリティクスのstart_timeとend_timeの値を決定します。
      • 最小のactivity_start_timeを探します。この値を切り捨てます。
      • 最大のactivity_end_timeを探します。この値を切り上げます。
    3. アナリティクスリクエストを行います。
      • エンティティIDを20件ずつのバッチにグループ化します。
      • 手順3bのstart_timeとend_timeの値を使用します。
      • 該当するplacement値を指定します。
    4. データストアに書き込みます。

Python SDKを使用する例については、active_entities.pyを参照してください。

フリークエンシー

最初の質問に対する回答によって、アクティブエンティティリクエストで使用する時間範囲が決まります。たとえば、アクティブエンティティについての情報を1時間ごとにリクエストする場合は、時間範囲は1時間になります。アクティブエンティティについての情報のリクエストが1日に1回の場合は、時間範囲は1日になります。つまり、現在のリクエストのstart_timeが前のリクエストのend_timeと等しくなるように時間範囲を選択する必要があります。

注: 時間枠のリクエストは1回のみにする必要があります。時間枠を複数回リクエストすると、不要なアナリティクスリクエストが発生することになります（下の例外）。

現在の時間に対して1時間に複数回のアナリティクスをリクエストするパートナーの場合は、同じパターンを適用します。つまり、フリークエンシーによって時間範囲が決まります。次の表は、このシナリオにおけるアクティブエンティティの開始と終了のタイムスタンプの例を示しています。

リクエスト時間 start_timeのタイムスタンプ end_timeのタイムスタンプ
00:15:00 00:00:00 00:15:00
00:30:00 00:15:00 00:30:00
00:45:00 00:30:00 00:45:00
01:00:00 00:45:00 01:00:00

変更イベントの格納方法を指定すると、上述の4つのアクティブエンティティリクエストすべてが同じ1時間ごとのバケットをクエリします。これは、このユースケースに求められる動作です。ただし、現在の時間が過ぎると、この1時間ごとのバケットはクエリされなくなります。

アクティビティの時間

アクティビティの開始時間と終了時間を利用する場合は、次の方法をお勧めします。アクティブエンティティの応答内のすべてのオブジェクトから、最小のactivity_start_timeと最大のactivity_end_timeを探します。最小のアクティビティの開始時間を切り捨て、最大のアクティビティの終了時間を切り上げて、これらの値を変更します。具体的には、次の表に示すように、両方のタイムスタンプをゼロに設定し、終了時間に1日を加えます。これらは、後続のアナリティクスリクエストで指定する開始時間と終了時間です。

最小、最大のアクティビティの時間 得られる時間
2019-03-04T20:55:20Z

2019-03-05T14:40:59Z		 2019-03-04T00:00:00Z

2019-03-06T00:00:00Z

注: 時、分、秒をゼロに設定したタイムスタンプを含めることが重要です。ゼロに設定せず、日付のみを渡した場合、広告アカウントのタイムゾーンの午前0時に開始および終了するアナリティクスをリクエストすることになり、必要な結果を得られないことがあります。たとえば、最小のアクティビティの開始時間が2019-02-28T01:30:07Zで、広告アカウントのタイムスタンプが-08：00：00のオフセットで省略された場合、アナリティクスリクエストは01:30から08:00の間に発生した変更を見逃してしまいます。

あるいは、時間を丸一日に拡張せずに、返されたアクティビティの時間枠についてのみアナリティクスをリクエストすることもできます。この方法を使用して得られる開始時間と終了時間は、それぞれ2019-03-04T20:00:00Zと2019-03-05T15:00:00Zになります（アナリティクスリクエストでDAYの詳細度を指定した場合、これらの範囲は使用できません）。

例

このセクションでは、アクティブエンティティを同期アナリティクスエンドポイントと組み合わせて使用​​する方法について説明します（わかりやすいように、応答を多少修正しています）。 この例では、アクティブエンティティエンドポイントが各時間の最初に呼び出され、各リクエストは前の時間を調べます。応答により、同期アナリティクスエンドポイントの使用方法が特定されます。

最初のアクティブエンティティリクエストは、03:00:00に行われます。応答は、行項目dvcz7のメトリックが変更されたこと、それらの変更イベントが02:02:55から02:28:12までの時間枠で適用されることを示します。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"

{
  "request": {},
  "data": [
    {
      "entity_id": "dvcz7",
      "activity_start_time": "2019-02-11T02:02:55Z",
      "activity_end_time": "2019-02-11T02:58:12Z",
      "placements": [
        "ALL_ON_TWITTER"
      ]
    }
  ]
}

これらのアクティビティの開始時間と終了時間に基づいて、上述の方法を使用し、アナリティクスのstart_timeとend_timeの値を、それぞれ2019-02-11T00:00:00Zと2019-02-12T00:00:00Zに設定します。次の各メトリクス配列の3番目の要素は、アクティブエンティティ情報に基づいて予想したとおり、ゼロ以外の値になっています。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"

{
  "data_type": "stats",
  "time_series_length": 24,
  "data": [
    {
      "id": "dvcz7",
      "id_data": [
        {
          "segment": null,
          "metrics": {
            "impressions": [
              0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ],
            "engagements": [
              0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ],
            "video_total_views": [
              0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ]
          }
        }
      ]
    }
  ],
  "request": {}
}

次のアクティブエンティティリクエストは04:00:00に発生し、前の時間のみを調べます。上述のとおり、時間枠のリクエストは1回のみにする必要があります。応答によると、この行項目の変更イベントは、02:00:00と03:00:00の両方に適用されることがわかります。後続のアナリティクスリクエストでは、両方の時間で変更が見られることになります。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"

{
  "request": {},
  "data": [
    {
      "entity_id": "dvcz7",
      "activity_start_time": "2019-02-11T02:07:17Z",
      "activity_end_time": "2019-02-11T03:49:22Z",
      "placements": [
        "ALL_ON_TWITTER"
      ]
    }
  ]
}

03:00:00にゼロ以外のメトリックが表示されるだけでなく、インプレッション数、滞在時間、MRC動画の再生数が以前の値から更新されていることがわかります。たとえば、02:00:00の時点でのインプレッション数は2,995であり、2,792から増加しています。これは、03:00:00の時間中に記録された変更イベントが02:00:00の時間にどのように適用されるかを示しています。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"

{
  "data_type": "stats",
  "time_series_length": 24,
  "data": [
    {
      "id": "dvcz7",
      "id_data": [
        {
          "segment": null,
          "metrics": {
            "impressions": [
              0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ],
            "engagements": [
              0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ],
            "video_total_views": [
              0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ]
          }
        }
      ]
    }
  ],
  "request": {}
}

05:00:00のアクティブエンティティリクエストは、前の1時間のみを見て、変更イベントが03:00:00の時間にのみ適用されることを示しています。後続のリクエストにおけるアナリティクスメトリックへの変更は、これを反映しています。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"

{
  "request": {},
  "data": [
    {
      "entity_id": "dvcz7",
      "activity_start_time": "2019-02-11T03:42:39Z",
      "activity_end_time": "2019-02-11T03:48:48Z",
      "placements": [
        "ALL_ON_TWITTER"
      ]
    }
  ]
}

アナリティクスの応答は、03:00:00の時間のメトリックのみが変更されたことを示しています。02:00:00の時間の値は、前のアナリティクスリクエストのときの値と同じです。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"

{
  "data_type": "stats",
  "time_series_length": 24,
  "data": [
    {
      "id": "dvcz7",
      "id_data": [
        {
          "segment": null,
          "metrics": {
            "impressions": [
              0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ],
            "engagements": [
              0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ],
            "video_total_views": [
              0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
            ]
          }
        }
      ]
    }
  ],
  "request": {}
}

最後に、06:00:00では、追加の変更イベントがないことがわかります。注: ただし、この行項目のメトリックを今後変更できないというわけではありません。

twurl -H ads-api.x.com "/9/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"

{
  "request": {},
  "data": []
}