API Thông tin chi tiết

Cung cấp một giao diện nhất quán và duy nhất để truy xuất số liệu thống kê quảng cáo.

Số liệu chia nhỏ - Kết quả theo nhóm
Số liệu hành động chia nhỏ - Tìm hiểu phản hồi từ số liệu hành động chia nhỏ.
Tác vụ không đồng bộ - Đối với các yêu cầu có lượng kết quả lớn, hãy sử dụng tác vụ không đồng bộ
Giới hạn và cách làm tốt nhất - Các giới hạn lệnh gọi, quá trình lọc và cách làm tốt nhất.

Trước khi có được dữ liệu về hiệu quả quảng cáo, bạn nên thiết lập quảng cáo để theo dõi các số liệu mà mình quan tâm. Để làm được điều đó, bạn có thể dùng Thẻ URL, Meta Pixel và API Chuyển đổi.

Những điểm cập nhật về iOS 14.5

Nhằm thích ứng với chính sách mới của Apple, chúng tôi thông báo những thay đổi quan trọng sẽ ảnh hưởng đến Khoảng thời gian phân bổ.

Để tìm hiểu thêm về việc các yêu cầu đối với iOS 14.5 của Apple sẽ tác động như thế nào đến quảng cáo trên Facebook, hãy xem các bài viết trong Trung tâm trợ giúp doanh nghiệp và nhật ký thay đổi của chúng tôi:

Những điểm cuối bị ảnh hưởng

GET /{ad-account-id}/insights
GET /{ad-id}/insights
GET /{ad-set-id}/insights
GET /{campaign-id}/insights
POST /{ad-account-id}/insights
POST /{ad-id}/insights
POST /{ad-set-id}/insights
POST /{campaign-id}/insights

Trước khi bắt đầu

Bạn sẽ cần:

Quyền ads_read.
Ứng dụng. Hãy xem bài viết Phát triển ứng dụng trên Meta để biết thêm thông tin.

Số liệu thống kê về chiến dịch

Cách lấy số liệu thống kê về hiệu quả của chiến dịch trong 7 ngày qua:

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Để tìm hiểu thêm, hãy xem phần Thông tin chi tiết về quảng cáo, Tài liệu tham khảo.

Thực hiện lệnh gọi

API Thông tin chi tiết có sẵn dưới dạng cạnh trên bất kỳ đối tượng quảng cáo nào.

Phương thức API
`act_<AD_ACCOUNT_ID>/insights`
`<CAMPAIGN_ID>/insights`
`<ADSET_ID>/insights`
`<AD_ID>/insights`

Yêu cầu

Bạn có thể yêu cầu các trường cụ thể qua danh sách được phân tách bằng dấu phẩy trong thông số fields. Ví dụ:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Phản hồi

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Cấp độ

Tổng hợp kết quả ở cấp độ đối tượng đã xác định. Thao tác này sẽ tự động loại bỏ dữ liệu trùng lặp.

Yêu cầu

Ví dụ: lấy thông tin chi tiết của chiến dịch ở cấp độ quảng cáo.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

Phản hồi

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Nếu bạn không có quyền truy cập vào tất cả đối tượng quảng cáo ở cấp độ yêu cầu, lệnh gọi thông tin chi tiết sẽ không trả về dữ liệu nào. Ví dụ: khi yêu cầu thông tin chi tiết có level được đặt là ad, nếu bạn không có quyền truy cập vào một hoặc nhiều đối tượng quảng cáo trong tài khoản quảng cáo thì lệnh gọi API này sẽ trả về lỗi quyền.

Khoảng thời gian phân bổ

Những điểm cập nhật về iOS 14 trở lên

Khi action_attribution_windows không được đặt, giá trị phân bổ mặc định sẽ là 7d_click và 1d_view. Sau khi bắt đầu thực thi, số lượt xem trong 28 ngày sẽ không còn. Khi đó, hệ thống sẽ trả về dữ liệu trống.
Đối với những quảng cáo cũ không hoạt động có giá trị khoảng thời gian phân bổ là 28 ngày, chúng tôi sẽ trả về dữ liệu này.
Sau khi thực thi, khoảng thời gian ở cấp độ tài khoản hoặc khoảng thời gian mặc định sẽ được đặt thành 7 ngày.
Trường use_account_attribution_setting không còn được dùng nữa. Thay vào đó, đối với các yêu cầu liên quan đến trường này, chúng tôi sẽ đặt action_attribution_windows thành giá trị mặc định là 7d_click và 1d_view.

Vui lòng xem Nhật ký về các thay đổi quan trọng của chúng tôi để biết thêm thông tin về những thay đổi liên quan đến iOS 14.

Khoảng thời gian phân bổ chuyển đổi đưa ra khung thời gian để xác định thời điểm chúng tôi phân bổ một sự kiện cho quảng cáo trong ứng dụng trên Meta. Để biết thông tin cơ bản, hãy xem Trung tâm trợ giúp doanh nghiệp của Meta, Giới thiệu về khoảng thời gian phân bổ. Chúng tôi đo lường các hành động diễn ra khi xảy ra một sự kiện chuyển đổi và xem lại thời điểm 1 ngày và 7 ngày trước. Để xem các hành động được phân bổ cho những khoảng thời gian phân bổ khác nhau, hãy gửi yêu cầu đến /{ad-account-id}/insights. Nếu bạn không cung cấp action_attribution_windows, chúng tôi sẽ sử dụng 7d_click, đồng thời cung cấp thông số này trong value.

Ví dụ: chỉ định action_attribution_windows và "value" được cố định ở khoảng thời gian phân bổ là 7d_click. Gửi yêu cầu đến act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] và nhận được kết quả sau:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Mở rộng trường

Yêu cầu các trường ở cấp độ nút và theo các trường được chỉ định trong phần mở rộng trường.

Yêu cầu

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

Phản hồi

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Sắp xếp

Sắp xếp các kết quả bằng cách cung cấp thông số sort cùng với {fieldname}_descending hoặc {fieldname}_ascending:

Yêu cầu

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

Phản hồi


{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Nhãn quảng cáo

Số liệu thống kê cho tất cả các nhãn có tên giống nhau. Được tổng hợp thành một giá trị duy nhất ở cấp độ đối tượng quảng cáo. Hãy xem phần Nhãn quảng cáo, Tài liệu tham khảo để biết thêm thông tin.

Yêu cầu

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Phản hồi

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Định nghĩa về lượt click

Để hiểu rõ hơn các số liệu lượt click mà Meta cung cấp hiện nay, vui lòng đọc định nghĩa và cách sử dụng của mỗi số liệu dưới đây:

Lượt click vào liên kết, actions:link_click - Số lượt click vào liên kết quảng cáo đến một số trang đích hoặc trải nghiệm trên hoặc ngoài tài sản thuộc sở hữu của Meta. Hãy xem Trung tâm trợ giúp quảng cáo, Lượt click vào liên kết
Lượt click (Tất cả), clicks - Số liệu này tính đến nhiều kiểu click vào quảng cáo, bao gồm cả một số kiểu tương tác với vùng chứa quảng cáo, liên kết đến đích đến khác và liên kết đến trải nghiệm quảng cáo mở rộng. Hãy xem phần Lượt click (Tất cả) trong Trung tâm trợ giúp quảng cáo

Đối tượng đã xóa và đã lưu trữ

Đơn vị quảng cáo có thể là DELETED hoặc ARCHIVED. Số liệu thống kê về đối tượng đã xóa hoặc đã lưu trữ sẽ hiển thị khi bạn truy vấn đối tượng cấp trên tương ứng. Nghĩa là nếu bạn truy vấn impressions ở cấp độ nhóm quảng cáo, các kết quả sẽ bao gồm impressions từ mọi quảng cáo trong nhóm đó, bất kể quảng cáo ở trạng thái đã xóa hay lưu trữ. Hãy xem thêm phần Cách tốt nhất để lưu trữ và truy xuất đối tượng quảng cáo.

Tuy nhiên, nếu bạn quy vấn bằng cách lọc, tùy chọn lọc theo trạng thái sẽ mặc định được áp dụng để chỉ trả về những đối tượng Đang hoạt động. Do đó, tổng số liệu thống kê của nút cấp trên có thể lớn hơn số liệu thống kê của nút cấp dưới.

Tuy nhiên, bạn có thể lấy số liệu thống kê về đối tượng ARCHIVED từ nút cấp trên tương ứng bằng cách cung cấp thông số filtering bổ sung.

Yêu cầu

Cách lấy số liệu thống kê về tất cả quảng cáo ARCHIVED trong tài khoản quảng cáo được liệt kê lần lượt:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

Phản hồi

Lưu ý rằng chỉ đối tượng đã lưu trữ mới được trả về trong phản hồi này.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Thông tin chi tiết về đối tượng đã xóa

Bạn có thể truy vấn thông tin chi tiết về đối tượng đã xóa nếu có ID tương ứng hoặc bằng cách sử dụng bộ lọc ad.effective_status.

Yêu cầu

Chẳng hạn như khi bạn có ID nhóm quảng cáo:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"

Trong ví dụ này, chúng tôi truy vấn bằng ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Phản hồi

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Khắc phục sự cố

Hết thời gian chờ

Các vấn đề thường gặp nhất gây ra lỗi ở điểm cuối này là có quá nhiều yêu cầu và lượt hết thời gian chờ:

Trên /GET hoặc các yêu cầu đồng bộ, bạn có thể gặp lỗi hết bộ nhớ hoặc hết thời gian chờ.
Trên /POST hoặc các yêu cầu không đồng bộ, bạn có thể gặp lỗi hết thời gian chờ. Đối với yêu cầu không đồng bộ, hệ thống có thể mất tới một giờ để hoàn tất một yêu cầu, bao gồm cả những lần thử lại. Ví dụ: nếu bạn thực hiện truy vấn nhằm cố gắng tìm nạp lượng dữ liệu lớn cho nhiều đối tượng ở cấp độ quảng cáo.

Đề xuất

Không có giới hạn rõ ràng về thời điểm truy vấn gặp lỗi. Khi truy vấn hết thời gian chờ, hãy thử chia nhỏ truy vấn đó thành các truy vấn nhỏ hơn bằng cách đưa vào bộ lọc như khoảng ngày.
Các số liệu duy nhất sẽ tốn thời gian tính toán. Hãy thử truy vấn các số liệu duy nhất trong một lệnh gọi riêng biệt để cải thiện hiệu quả của các số liệu không duy nhất.

Giới hạn tốc độ

API Thông tin chi tiết từ Meta sử dụng giới hạn tốc độ để đảm bảo trải nghiệm báo cáo tối ưu cho mọi đối tác của chúng tôi. Để biết thêm thông tin và gợi ý, hãy xem Giới hạn và cách làm tốt nhất về API Thông tin chi tiết của chúng tôi.

Khác biệt với Trình quản lý quảng cáo

Hành vi mặc định của API khác với hành vi mặc định trong Trình quản lý quảng cáo. Nếu bạn muốn thấy hành vi tương tự như trong Trình quản lý quảng cáo, vui lòng đặt trường use_account_attribution_setting thành true.

Tìm hiểu thêm

Bất kỳ điểm cuối nào không có trong danh sách ở trên sẽ không thuộc API này. Nếu bạn định đưa các báo cáo của Meta vào giải pháp của mình, hãy xem Điều khoản về nền tảng của Meta và Chính sách về API Marketing dành cho nhà phát triển.