Instagram 媒體洞察報告

代表 Instagram 媒體物件上的社交互動衡量數據。

建立

不支援這項操作。

讀取

GET /{ig-media-id}/insights

獲取 Instagram 媒體物件的洞察報告資料。

限制

• 洞察報告資料不適用於 Instagram 媒體相簿中的任何媒體。
• 即使限時動態已獲典藏或設為精選，限時動態媒體的衡量數據也只在 24 小時內有效。如果您希望在限時動態過期之前獲得最新洞察報告，請為 Instagram 主題設定 Webhooks，並訂閱 story_insights 欄位。
• 限時動態媒體衡量數據的數值若小於 5，系統將傳回錯誤代碼 10，並顯示訊息 (#10) Not enough viewers for the media to show insights。
• 對於歐洲和日本用戶所製作的限時動態，replies 衡量數據目前將傳回數值 0。
• 對於限時動態，歐洲和日本用戶作出的回覆將不會包含在 replies 計算中。
• 如果您正在要求的洞察報告資料不存在或者目前無法提供，API 將為個別衡量數據傳回空資料集，而不是傳回 0。
• 用於計算衡量數據的數據最多可延遲 48 小時。

必要條件

要求語法

GET https://graph.facebook.com/{api-version}/{ig-media-id}/insights
  ?metric={metric}
  &access_token={access-token}

路徑參數

查詢字串參數

衡量數據

相簿衡量數據

相片和影片衡量數據

不支援為相簿中的媒體提供衡量數據，請改為選擇相簿衡量數據。

Reels 連續短片衡量數據

限時動態衡量數據

要求範例

curl -X GET \
  'https://graph.facebook.com/v19.0/17895695668004550/insights?metric=impressions,reach&access_token=IGQVJ...'

回應範例

{
  "data": [
    {
      "name": "impressions",
      "period": "lifetime",
      "values": [
        {
          "value": 264
        }
      ],
      "title": "Impressions",
      "description": "Total number of times the media object has been seen",
      "id": "17855590849148465/insights/impressions/lifetime"
    },
    {
      "name": "reach",
      "period": "lifetime",
      "values": [
        {
          "value": 103
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen the media object",
      "id": "17855590849148465/insights/reach/lifetime"
    }
  ]
}

全新衡量數據

要求語法

GET https://graph.facebook.com/{api-version}/{ig-media-id}/insights
  ?metric={metric}
  &breakdown={breakdown}
  &access_token={access-token}

路徑參數

查詢字串參數

資料細節

您也可以指定一項或多項資料細節，結果將根據指定的資料細節相應地細分為更小的組合。值可以是：

• action_type：僅與 profile_activity 衡量數據相容。按照觀眾在查看應用程式用戶的個人檔案後所點按或點擊的個人檔案用戶介面元件來細分結果。回應值為：

  • BIO_LINK_CLICKED
  • CALL
  • DIRECTION
  • EMAIL
  • OTHER
  • TEXT
• story_navigation_action_type：按照觀眾在查看媒體時採取的導覽動作來細分結果。

  • TAP_BACK
  • TAP_EXIT
  • TAP_FORWARD
  • SWIPE_FORWARD

請參閱衡量數據表，以確定哪些衡量數據支援資料細節，及其支援哪些資料細節。如果您要求取得不支援資料細節的衡量數據，API 將傳回一個錯誤（「An unknown error has occurred.」），因此如果在單個查詢中索取多項衡量數據，請加倍小心。

衡量數據

帖子衡量數據

以下衡量數據適用於作為帖子發佈的圖片和影片類 Instagram 媒體。相簿輪播廣告和 IGTV 不受支援。

限時動態衡量數據

以下衡量數據適用於作為限時動態發佈的 Instagram 媒體。

回應

包含查詢結果的 JSON 物件。視乎您的查詢規格，結果可以包含下列資料：

{
  "data": [
    {
      "name": "{name}",
      "period": "{period}",
      "values": [
        {
          "value": {value}
        }
      ],
      "title": "{title}",
      "description": "{description}",
      "total_value": {
        "value":{value},
        "breakdowns": [
          {
            "dimension_keys": [
              "{dimension-key-1}",
              "{dimension-key-2}"
              ...
            ],
            "results": [
              {
                "dimension_values": [
                  "dimension-value-1",
                  "dimension-value-2"
                  ...
                ],
                "value": {value}
              },
              ...
            ]
          }
        ]
      },
      "id": "{id}"
    }
  ]
}

回應內容

帖子衡量數據要求範例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/17932174733377207/insights?metric=profile_activity&breakdown=action_type&access_token=EAAOc..."

帖子衡量數據回應範例

{
  "data": [
    {
      "name": "profile_activity",
      "period": "lifetime",
      "values": [
        {
          "value": 4
        }
      ],
      "title": "Profile activity",
      "description": "[IG Insights] This header is the name of a metric that appears on an educational info sheet for a particular post, story, video or promotion. This metric is the sum of all profile actions people take when they engage with this content.",
      "total_value": {
        "value": 4,
        "breakdowns": [
          {
            "dimension_keys": [
              "action_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "email"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "text"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "direction"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "bio_link_clicked"
                ],
                "value": 1
              }
            ]
          }
        ]
      },
      "id": "17932174733377207/insights/profile_activity/lifetime"
    }
  ]
}

限時動態衡量數據要求範例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/17969782069736348/insights?metric=navigation&breakdown=story_navigation_action_type&access_token=EAAOc..."

限時動態衡量數據回應範例

{
  "data": [
    {
      "name": "navigation",
      "period": "lifetime",
      "values": [
        {
          "value": 25
        }
      ],
      "title": "Navigation",
      "description": "This is the total number of actions taken from your story. These are made up of metrics like exited, forward, back and next story.",
      "total_value": {
        "value": 25,
        "breakdowns": [
          {
            "dimension_keys": [
              "story_navigation_action_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "tap_forward"
                ],
                "value": 19
              },
              {
                "dimension_values": [
                  "tap_back"
                ],
                "value": 4
              },
              {
                "dimension_values": [
                  "tap_exit"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "swipe_forward"
                ],
                "value": 1
              }
            ]
          }
        ]
      },
      "id": "17969782069736348/insights/navigation/lifetime"
    }
  ]
}

更新

不支援這項操作。

刪除

不支援這項操作。