API Sự kiện trong ứng dụng

Sự kiện trong ứng dụng cho phép bạn theo dõi các hành động diễn ra trong ứng dụng di động hoặc trang web của mình, chẳng hạn như lượt cài đặt ứng dụng và sự kiện mua hàng. Bằng cách theo dõi những sự kiện này, bạn có thể đo lường hiệu quả quảng cáo và xây dựng đối tượng để nhắm mục tiêu quảng cáo.

Để biết thông tin về cách theo dõi Sự kiện trong ứng dụng dành cho tính năng Nhắn tin cho doanh nghiệp, vui lòng xem phần API Sự kiện trong ứng dụng dành cho tính năng Nhắn tin cho doanh nghiệp trong tài liệu về Nền tảng Messenger của chúng tôi.

Cách hoạt động

Có 3 loại Sự kiện trong ứng dụng:

• Sự kiện được ghi tự động - Facebook SDK tự động ghi lại lượt cài đặt ứng dụng, số phiên trên ứng dụng và lượt mua hàng trong ứng dụng.
• Sự kiện tiêu chuẩn - Các sự kiện phổ biến mà Facebook đã tạo cho bạn.
• Sự kiện tùy chỉnh - Các sự kiện bạn tạo riêng cho ứng dụng của mình.

Sự kiện trong ứng dụng có 3 phần:

1. name - Chuỗi bắt buộc mô tả sự kiện. Tên xuất hiện trong Nhật ký sự kiện khi sự kiện trong ứng dụng được gửi đến công cụ Phân tích.
2. valueToSum - Một giá trị không bắt buộc mà công cụ Phân tích thêm vào các giá trị Value To Sum khác từ sự kiện trong ứng dụng có cùng tên.
3. parameters - Các giá trị không bắt buộc đi kèm sự kiện trong ứng dụng của bạn.

Số lượng tên sự kiện khác nhau tối đa là 1.000. Lưu ý: Không có loại sự kiện mới nào được ghi sau khi đạt đến giới hạn này và nếu vượt quá giới hạn này, bạn có thể gặp lỗi 100 Invalid parameter khi ghi. Tuy nhiên, bạn có thể vô hiệu hóa các sự kiện cũ. Hãy đọc thêm về giới hạn sự kiện trong phần Câu hỏi thường gặp.

Trước khi bắt đầu

Bạn sẽ cần có:

• ID nhà quảng cáo, ID quảng cáo từ thiết bị Android hoặc Mã nhận dạng quảng cáo (IDFA) từ thiết bị Apple
• Mã truy cập ứng dụng để Facebook xác thực. Không lưu trữ mã truy cập ứng dụng trên máy khách.

Lượt cài đặt ứng dụng

Gửi yêu cầu POST từ máy chủ của bạn đến điểm cuối /{app-id}/activities cùng với các thông số application_tracking_enabled và advertiser_tracking_enabled:

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi sau đây:

{
  "success": true
}

Cảnh báo

• Bạn chỉ nên báo cáo một lượt cài đặt trên mỗi người dùng. Loại bỏ ID trùng lặp ở cấp độ ID và người dùng nếu có thể.

Hãy truy cập Hướng dẫn tham khảo về Hoạt động của ứng dụng của chúng tôi để biết danh sách các thông số có sẵn.

Cho phép theo dõi quảng cáo

Trường advertiser_tracking_enabled cho biết liệu một người đã bật tính năng theo dõi quảng cáo trên thiết bị của họ hay chưa. Đặt thành 0 để tắt hoặc 1 để bật. Bạn nên tìm nạp dữ liệu này và gửi trả lại cho Facebook để xác định xem tính năng theo dõi quảng cáo có thể được dùng cho mục tiêu tối ưu hóa hoặc chuyển đổi hay không. Meta sẽ sử dụng dữ liệu sự kiện (từ các đối tác về hoạt động của người dùng bên ngoài Meta) theo Chính sách dữ liệu của Meta, kể cả cho mục đích báo cáo quảng cáo, phát hiện gian lận, cũng như xây dựng và cải thiện sản phẩm (bao gồm sản phẩm phân phối quảng cáo).Tuy nhiên, Meta sẽ hạn chế sử dụng dữ liệu về người đó để cá nhân hóa quảng cáo cho người dùng đó. Đối với những thiết bị chạy phiên bản cũ hơn iOS 6, thông số này nên mặc định là 1.

Hãy truy cập Tài liệu tham khảo AdSupport của Apple để lấy trạng thái theo dõi của người dùng.

Đoạn mã sau minh họa cách tìm nạp giá trị của cờ cho phép theo dõi này.

Bạn có thể lấy cài đặt hiện tại của cờ cho phép theo dõi này từ thuộc tính Settings.shared.isAdvertiserTrackingEnabled.

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

Không cho phép theo dõi quảng cáo

Bất kỳ ứng dụng nào cũng có thể chọn bao gồm cài đặt để người dùng tắt theo dõi quảng cáo trong ứng dụng đó. Facebook yêu cầu các đối tác phải đưa tùy chọn này vào SDK của họ và báo cáo lại cho Facebook về lựa chọn của người dùng cùng với sự kiện cài đặt hoặc chuyển đổi. Facebook sử dụng sự kiện cài đặt hoặc chuyển đổi để báo cáo quảng cáo nhưng hạn chế sử dụng sự kiện này cho việc tối ưu hóa quảng cáo. Cài đặt của người dùng phải nhất quán giữa các lần khởi chạy ứng dụng.

Sự kiện chuyển đổi

Gửi yêu cầu POST đến điểm cuối /{app-id}/activities có event được đặt thành CUSTOM_APP_EVENTS và đặt advertiser_tracking_enabled cho từng sự kiện riêng lẻ. Thông số advertiser_id hoặc attribution là bắt buộc.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi sau đây:

{
  "success": true
}

Phân bổ

Điểm cuối attribution trả về số lượt cài đặt và lượt chuyển đổi dựa trên lượt click đã diễn ra trên quảng cáo trong vòng 28 ngày. Trình quản lý quảng cáo sử dụng mô hình phân bổ lượt xem trong 1 ngày và lượt click trong 28 ngày và thông tin chi tiết được hiển thị dựa trên thời điểm hiển thị hoặc nhấp, chứ không phải thời điểm cài đặt hoặc chuyển đổi. Điều này quan trọng khi so sánh báo cáo của bạn với báo cáo của Trình quản lý quảng cáo trên Facebook. Ngoài các yêu cầu về sự kiện tiêu chuẩn trong ứng dụng là nhấp vào quảng cáo, bạn cũng nên lưu ý đến các tình huống sau:

• Yêu cầu phân bổ lượt xem - Việc đặt consider_views=TRUE sẽ trả về dữ liệu phân bổ cho lượt cài đặt đã diễn ra trong vòng 1 ngày kể từ khi hiển thị quảng cáo, với điều kiện tài khoản trong Trung tâm tài khoản không nhấp vào quảng cáo trong vòng 28 ngày. Phản hồi được trả về sẽ là is_view_through=TRUE và view_time sẽ thay thế click_time. Tất cả phân bổ khác đều giống như dữ liệu phân bổ lượt click vào quảng cáo.

• Yêu cầu trên nhiều chiến dịch - Nhà quảng cáo có thể theo dõi hiệu quả của tất cả các quảng cáo dẫn đến sự kiện trong ứng dụng. Facebook sẽ gửi yêu cầu về các sự kiện từ chiến dịch quảng cáo chừng nào mục tiêu chiến dịch không được đặt thành lượt cài đặt ứng dụng di động hoặc tương tác với ứng dụng di động. Dữ liệu này chỉ được hiển thị nếu nhà quảng cáo đã thêm ứng dụng vào trường “Theo dõi sự kiện trong ứng dụng di động” trong quảng cáo của họ.

• Trường hợp sử dụng - Nếu khách hàng của bạn muốn theo dõi số lượt cài đặt do quảng cáo bài viết trên Trang tạo ra hoặc số lượt click vào trang web chuyển người dùng đến trang web di động, họ có thể thực hiện điều này trong trình quản lý quảng cáo và Facebook sẽ xác nhận số lượt cài đặt ứng dụng có liên quan.

• Yêu cầu trên nhiều thiết bị - Nhà quảng cáo có ứng dụng trên nhiều nền tảng có thể xem dữ liệu về số lượt cài đặt ứng dụng thu được từ quảng cáo trên nhiều nền tảng đó.

• Trường hợp sử dụng - Một người dùng nhấp vào quảng cáo ứng dụng trên iPhone rồi cài đặt chính ứng dụng đó trên iPad của họ. Khi đó, chúng tôi có thể phân bổ lượt cài đặt ứng dụng trên iPad này là do quảng cáo trên iPhone mang lại bất kể tùy chọn nhắm mục tiêu quảng cáo là gì.

So khớp nâng cao

Khi sử dụng tính năng So khớp nâng cao, bạn có thể gửi dữ liệu khách hàng cho Facebook. Tại đây, chúng tôi sử dụng dữ liệu này để xác định chính xác hơn những tài khoản nào trong Trung tâm tài khoản đã hành động đối với quảng cáo của bạn. Với dữ liệu này, Facebook có thể so khớp các sự kiện chuyển đổi với khách hàng của bạn nhằm tối ưu hóa quảng cáo và xây dựng lượng đối tượng tiếp thị lại đông đảo hơn.

Gửi yêu cầu POST đến điểm cuối /{app-id}/activities có thông số ud được đặt thành một thông số sẽ giúp theo dõi khách hàng của bạn, chẳng hạn như email hoặc số điện thoại của khách hàng. Tất cả dữ liệu của khách hàng phải được băm. Nếu không, Facebook sẽ bỏ qua dữ liệu đó. Hãy nhớ đặt advertiser_tracking_enabled cho từng sự kiện riêng lẻ.

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

Khi thành công, ứng dụng của bạn sẽ nhận được phản hồi sau đây:

{
  "success": true
}

Bạn phải băm tất cả dữ liệu của người dùng bằng SHA256 trước khi gửi cho Facebook. Facebook sẽ bỏ qua dữ liệu không được băm.

Loại bỏ sự kiện trùng lặp

Đối với sự kiện trong ứng dụng, chúng tôi áp dụng chức năng loại bỏ sự kiện trùng lặp tương tự như chức năng dành cho sự kiện trên web. Logic này tận dụng chức năng loại bỏ sự kiện trùng lặp dựa trên trường event_id và event_name. Thông số event_id là thông tin nhận dạng có thể phân biệt rõ giữa các sự kiện tương tự nhau. ID sự kiện không chính xác có thể khiến hệ thống loại bỏ trùng lặp nhầm lượt chuyển đổi, do đó ảnh hưởng đến báo cáo lượt chuyển đổi và hiệu quả chiến dịch.

Thông tin thiết bị mở rộng

Gửi thông tin về thiết bị, chẳng hạn như chiều rộng và chiều cao màn hình, trong lệnh gọi sự kiện trong ứng dụng của bạn bằng /{app-id}/activities?extinfo. Các giá trị được phân tách bằng dấu phẩy và phải theo thứ tự được lập chỉ mục trong hướng dẫn tham khảo về /application/activites. Khi sử dụng extinfo, tất cả các giá trị đều bắt buộc.

• version phải là a2 dành cho Android
• version phải là i2 dành cho iOS

Tài liệu tham khảo

• Thông số ApplicationActivities
• Tài liệu dành cho nhà phát triển Android - Số liệu màn hình hiển thị
• Tài liệu dành cho nhà phát triển Android - Bộ nhớ ngoài
• Tài liệu dành cho nhà phát triển Apple - Số liệu màn hình hiển thị
• Tài liệu dành cho nhà phát triển Apple - Bộ nhớ ngoài
• Tài liệu dành cho nhà phát triển Apple - Kích thước màn hình

Lấy cookie di động

Bạn nên liên kết các sự kiện trong ứng dụng với một advertiser_id. Tuy nhiên, đối với các thiết bị Android và thiết bị iOS chạy phiên bản thấp hơn iOS 6, bạn cũng có thể sử dụng thông số attribution được đặt thành cookie di động của thiết bị.

Lưu ý: Cookie di động không bắt nguồn từ bất kỳ thuộc tính thiết bị hoặc người dùng nào. Những cookie này không cố định và được thiết kế nhằm cập nhật thường xuyên. Không sử dụng cookie di động cho các quảng cáo nhắm mục tiêu lại.

Android

Cookie là một chuỗi gồm 22 ký tự chữ và số ngẫu nhiên.

Lấy ID phân bổ của Facebook bằng ContentProvider:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Bạn cũng nên tìm nạp ID quảng cáo từ ứng dụng Android của bạn.

iOS

Cookie di động do các ứng dụng Facebook iOS tạo bằng CFUUIDCreateString và là chuỗi biểu thị UUID 128 bit.

Lấy cả ID cookie và IDFA rồi gửi cho Facebook làm thông tin nhận dạng:

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

Tiêu đề HTTP X-Forwarded-For

Nếu yêu cầu POST được thực hiện từ một vị trí trung tâm như máy chủ hoặc proxy - về cơ bản là lệnh gọi giữa các máy chủ - thì phải có tiêu đề X-Forwarded-For HTTP để đảm bảo thông tin thiết bị và vị trí chính xác. Hãy gửi địa chỉ IP của thiết bị, định dạng IPv4 hoặc IPv6, thông qua thông số tiêu đề X-Forwarded-For HTTP trong từng yêu cầu sự kiện trong ứng dụng mà bạn gửi. Khi bạn làm vậy, chúng tôi sẽ có thể ghép nối advertiser_id với đúng địa chỉ IP mà chúng tôi có thể sử dụng trong nền tảng của mình.

Ví dụ về IPv6

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

Ví dụ về IPv4

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

Thử nghiệm

1. Chuyển đến Trình quản lý sự kiện.
2. Nhấp vào biểu tượng Nguồn dữ liệu ở bên trái trang.
3. Chọn tên và ID của dữ liệu.
4. Nhấp vào Thử nghiệm sự kiện rồi chọn kênh làm Ứng dụng.
5. Gửi yêu cầu API Sự kiện trong ứng dụng bằng công cụ API Đồ thị.
6. Hoạt động tương tác của bạn sẽ sớm xuất hiện ở tab Thử nghiệm sự kiện.

Trường hợp sai lệch

Trong trường hợp máy khách so sánh báo cáo của một đối tác đo lường di động với báo cáo của Facebook và thấy có sự sai lệch, dưới đây là một số mục cần kiểm tra:

Nếu Facebook đang báo cáo ít lượt cài đặt hơn MMP:

• Facebook SDK có được tích hợp đúng cách không?
• Máy khách có đang sử dụng sai ID ứng dụng không?

Nếu Facebook đang báo cáo nhiều lượt cài đặt hơn MMP:

• Các khoảng thời gian phân bổ có giống nhau không? Facebook thường có khoảng thời gian ghi nhận lớn hơn hầu hết các đối tác đo lường di động.
• MMP SDK có được tích hợp đúng cách không?
• Máy khách có đang sử dụng sai ID ứng dụng không?
• Sự sai lệch chỉ có trên iOS7 phải không? MMP có đang nhận Mã nhận dạng quảng cáo của Apple (IDFA) từ thiết bị và chuyển số này đến Facebook đúng cách không?

Tài liệu tham khảo

Thông tin mở rộng về hoạt động của ứng dụng

Hãy xem hướng dẫn tham khảo về /application/activites để biết thêm chi tiết về thông tin mở rộng của ứng dụng.

Thông số dữ liệu người dùng

Tên sự kiện tiêu chuẩn

Thông số sự kiện tiêu chuẩn

Xem thêm

• Sự kiện trong ứng dụng
• Cách làm tốt nhất cho sự kiện trong ứng dụng
• Xử lý lỗi
• Tuân thủ GDPR
• Trình quản lý quảng cáo trên Facebook
• Bảng điều khiển ứng dụng Facebook