API Push V2.0 - dữ liệu thô theo thời gian thực (thử nghiệm mở rộng)

Khái quát: Dữ liệu sự kiện phân bổ được đẩy sang bạn theo thời gian thực để sử dụng trong các hệ thống CNTT của bạn. Bạn chọn các sự kiện phân bổ và dữ liệu được gửi đến điểm cuối dịch vụ web của bạn.

API Push V2.0

4409_Push_API_V2-01.png

  Push API news

  • Push API V2.0 is aligned with AppsFlyer raw data V5.0 specification used by other data delivery tools in AppsFlyer. It has over 40 additional attribution fields. As new fields are added they are made available rapidly in Push API V2.0.
  • Push API V1.0 will no longer be updated and will be discontinued.
  • Developer! Migration guide Push API V1.0 to Push API V2.0

Push API is used to get Attribution data in real-time so that you can combine in-house user data with the real-time attribution data from AppsFlyer. Use the data to follow user journeys and to perform real-time analytics and segmentation. 

If your app flow depends on attribution data in real-time (less than five seconds) consider using conversion data.

For more information about AppsFlyer data tools see: Choosing AppsFlyer data delivery tools, Using Push and Pull API together

Tính năng API Push

Event types supported by Push API
Loại chiến dịch Loại sự kiện Không tự nhiên Tự nhiên Nhắm mục tiêu lại
Thu hút người dùng Cài đặt  
Thu hút người dùng  Cài đặt các sự kiện trong ứng dụng  
Nhắm mục tiêu lại Thu hút lại (Re-engagement)    
Tái xác định mục tiêu  Sự kiện trong ứng dụng tương tác lại (Re-engagement in-app events)    
Tái xác định mục tiêu  Tái phân bổ     
Tái xác định mục tiêu  Sự kiện trong ứng dụng phân bổ lại    

Độ mới của dữ liệu

Push API messages are sent in real-time. 

Công nghệ

    • RESTful API, POST and GET methods supported
    • Phản hồi tin nhắn POST được chứa trong một JSON

 Chú ý

Some media sources, restrict the use of user-level data and the sharing of this data with third parties. Ensure that you comply with the media source terms of use.
For example, Facebook, Twitter, Snapchat, Pinterest.

Triển khai API Push

Thiết lập API Push

Implementation guidelines 

  • Các trường bổ sung có thể được thêm vào cấu trúc JSON tùy từng thời điểm mà không cần thông báo trước. Thực hiện theo bài viết này để được thông báo khi có thay đổi.
  • If your endpoint host fails to accept the Push API messages they can't be resent. If you lose Push API messages, use pull API to fill any gaps. 

Checklist

Complete this checklist before you setup Push API. 

  • Whitelist IPs: Whitelist AppsFlyer IP addresses so that they can communicate with the endpoint defined in the URL. List of AppsFlyer IP addresses.
  • TLS support:
  • Cổng: 80, 443
  • Endpoint:
    • Is a valid domain name
    • Configured to return HTTP status code 200 indicating successful completion. Note: No other status code is allowed. This includes other 2XX codes. 
    • Có thể sử dụng cùng một điểm cuối một lần trên mỗi ứng dụng. 
    • When using the GET method, do not add query parameters to the URL if the endpoint is hosted by third-party providers.
    • API key parameters aren't supported.

Thiết lập API Push

Để thêm điểm cuối API Push:

  1. Trong AppsFlyer, đi tới Tích hợp > Truy cập API.
    Cửa sổ Truy cập API mở ra. 
  2. Scroll down to the Push API section.
    The Push API endpoint section displays.

    PushAPi.png

  3. Nhấp vào Thêm Postback.
    Bạn có thể định cấu hình lên tới 6 điểm cuối API Push.
  4. Select an HTTP method: POST or GET
  5. Nhập Postback URL. 
  6. (Tùy chọn) Chọn phiên bản API Push: (mặc định) 2.0 
  7. Chọn một hoặc nhiều loại sự kiện sẽ được gửi đến URL điểm cuối. 
  8. Nhấp vào Lưu
    API Push hiện đang hoạt động
    Dữ liệu chuyển đổi được gửi đến điểm cuối.
  9. Kiểm tra điểm cuối bằng cách sử dụng quy trình sau.

Để kiểm tra điểm cuối:

  1. Nhấp vào Gửi kiểm tra. 
    Một thông báo kết quả kiểm tra sẽ hiển thị bên dưới nút Gửi kiểm tra
    Một thông báo kiểm tra được gửi đến điểm cuối.
  2. Check that the endpoint received the test message.
    A copy of the message sent follows.

Các mẫu thông báo POST và GET API

Mẫu thông báo POST

{
  "device_model":"GT-I9300",
  "fb_adgroup_id":"6032793211234",
  "download_time":"2015-10-28 00:18:00",
  "operator":"Vodafone IN",
  "click_time":"2015-10-28 12:17:37",
  "agency":null,
  "ip":"115.98.114.125",
  "cost_per_install":null,
  "fb_campaign_id":"6032793121234",
  "imei":"358422050231234",
  "is_retargeting":false,
  "app_name":"[App Name Comes Here]",
  "re_targeting_conversion_type":null,
  "android_id":"449021d533061234",
  "city":"London",
  "af_sub1":null,
  "af_sub2":null,
  "event_value":null,
  "af_sub3":null,
  "fb_adset_name":"FACEBOOK_ADSET_TEST",
  "af_sub4":null,
  "customer_user_id":"1234-5678",
  "mac":null,
  "af_sub5":null,
  "campaign":"FACEBOOK_CAMPAIGN_TEST",
  "event_name":null,
  "currency":null,
  "install_time":"2015-10-28 12:18:36",
  "fb_adgroup_name":"FACEBOOK_ADGROUP_TEST",
  "event_time":"2015-10-28 12:18:36",
  "platform":"android",
  "sdk_version":"1.17",
  "appsflyer_device_id":"1446034686662-8619927357095541234",
  "wifi":true,
  "advertising_id":"95e55150-1111-2222-3333-3e0c8c1d9978",
  "media_source":"Facebook Ads",
  "country_code":"GB",
  "http_referrer":null,
  "fb_campaign_name":"FACEBOOK_CAMPAIGN_TEST",
  "click_url":null,
  "carrier":"Vodafone",
  "language":"English",
  "app_id":"[App ID Comes Here]",
  "app_version":"4.4.1",
  "attribution_type":"regular",
  "af_siteid":null,
  "os_version":"4.3",
  "fb_adset_id":"6032793131234",
  "device_brand":"samsung",
  "event_type":"install",
  "af_ad": "a86721874",
  "af_ad_id": "123245353",
  "af_ad_type":"Banner_210X600",
  "af_adset":"3gvow",
  "af_adset_id":"3gvow",
  "af_c_id":"3e025",
  "af_channel":"youtube",
  "af_cost_currency":"USD",
  "af_cost_model":"cpi",
  "af_cost_value":"0.0750",
  "af_keywords":"key1 key2 key3"
}

Mẫu thông báo GET

?mac%3D%26af_sub1%3D%26customer_user_id%3D1234-5678%26af_cost_value%3D0.0750%26
app_version%3D4.4.1%26city%3DLondon%26fb_campaign_id%3D6032793121234%26device_model%3DGT-I9300%26af_cost_model%3Dcpi%26af_c_id%3D3e025%26app_name%3D%5BApp%20Name%20Comes%20Here%5D%26wifi%3Dtrue%26install_time%3D2015-10-28%2012%3A18%3A36%26operator%3DVodafone%20IN%26fb_adgroup_id%3D6032793211234%26currency%3D%26af_adset_id%3D3gvow%26re_targeting_conversion_type%3D%26is_retargeting%3Dfalse%26country_code%3DGB%26event_type%3Dinstall%26appsflyer_device_id%3D1446034686662-8619927357095541234%26http_referrer%3D%26af_sub5%3D%26fb_campaign_name%3DFACEBOOK_CAMPAIGN_TEST%26click_url%3D%26media_source%3DFacebook%20Ads%26campaign%3DFACEBOOK_CAMPAIGN_TEST%26af_keywords%3Dkey1%20key2%20key3%26event_value%3D%26ip%3D115.98.114.125%26event_time%3D2015-10-28%2012%3A18%3A36%26click_time%3D2015-10-28%2012%3A17%3A37%26af_sub4%3D%26imei%3D358422050231234%26fb_adgroup_name%3DFACEBOOK_ADGROUP_TEST%26af_sub2%3D%26attribution_type%3Dregular%26android_id%3D449021d533061234%26af_adset%3D3gvow%26fb_adset_id%3D6032793131234%26af_ad%3Da86721874%26agency%3D%26fb_adset_name%3DFACEBOOK_ADSET_TEST%26cost_per_install%3D%26af_channel%3Dyoutube%26af_cost_currency%3DUSD%26device_brand%3Dsamsung%26download_time%3D2015-10-28%2000%3A18%3A00%26af_siteid%3D%26language%3DEnglish%26app_id%3D%5BApp%20ID%20Comes%20Here%5D%26af_ad_type%3DBanner_210X600%26carrier%3DVodafone%26event_name%3D%26advertising_id%3D95e55150-1111-2222-3333-3e0c8c1d9978%26os_version%3D4.3%26platform%3Dandroid%26af_sub3%3D%26af_ad_id%3D123245353%26sdk_version%3D1.17

Xóa các Postback

Để xóa Postback:

  1. Go to Integration > API Access.
    Scroll down to the Push API access section. 
  2. Nhấp vào Xóa Postback.
  3. Nhấp vào Lưu.
    Postback được gỡ bỏ. 

Cấu trúc thông báo API Push

Phản hồi của API Push phụ thuộc vào phương thức HTTP:

  • GET: data parameters are appended to the URL string
  • POST: tham số dữ liệu được chứa trong phần nội dung thông báo ở định dạng JSON

Các trường API Push

Push API messages contain the fields as described here. Additional fields will be added from time to time as these are added to the AppsFlyer platform Your import/parsing mechanisms should take this into account. 

Các trường API duy nhất
Tên hiển thị Tên V2.0 Nhận xét 
Tiền tệ đã chọn selected_currency  
Doanh thu bằng loại tiền đã chọn doanh_thu_bằng_loại_tiền_
đã_chọn
 
Chi phí bằng loại tiền đã chọn chi_phí_bằng_loại_tiền_
đã_chọn
 
Múi giờ thời gian tải xuống đã chọn múi_giờ_thời_gian_tải_xuống_đã_
chọn
 
Múi giờ thời gian tương tác được phân bổ đã chọn múi_giờ_thời_gian_tương_
tác_được_phân_bổ_đã_chọn
 
Múi giờ thời gian cài đặt đã chọn múi_giờ_thời_gian_cài_đặt_
đã_chọn
 
Múi giờ thời gian sự kiện đã chọn múi_giờ_thời_gian_sự_
kiện_đã_chọn
 
Múi giờ đã chọn múi_giờ_đã_chọn  
URL Liên kết sâu deeplink_url Có sẵn từ 2019/Q4
OAID OAID Có sẵn từ 2019/Q4
ID từ khóa keyword_id Có sẵn từ 2019/Q4
Lưu trữ lượt cài đặt lại store_reinstall (False=Tải về, True=Tải về lại) Có sẵn từ 2019/Q4

Toàn bộ danh sách các trường API Push

Tên API Push V2.0 Tên hiển thị API Push Nhận xét
advertising_id ID quảng cáo  
af_ad Quảng cáo  
af_ad_id ID Quảng cáo  
af_ad_type Loại Quảng cáo  
af_adset Bộ quảng cáo  
af_adset_id ID Bộ quảng cáo  
af_attribution_lookback Cửa sổ xem lại phân bổ  
af_c_id ID Chiến dịch  
af_channel Kênh  
af_cost_currency Đơn vị tiền tệ của chi phí  
af_cost_model Mô hình Chi phí  
af_cost_value Giá trị Chi phí  
af_keywords Từ khóa  
af_prt Đối tác  
af_reengagement_window Cửa sổ Tương tác lại  
af_siteid ID trang  
af_sub_siteid ID Trang phụ  
af_sub1 Thông số phụ 1  
af_sub2 Thông số phụ 2  
af_sub3 Thông số phụ 3  
af_sub4 Thông số phụ 4  
af_sub5 Thông số phụ 5  
amazon_aid Amazon Fire ID  
android_id ID Android  
phiên_bản_api Phiên bản API  
app_id ID ứng dụng  
app_name Tên ứng dụng  
app_version Phiên bản ứng dụng  
appsflyer_id ID AppsFlyer  
attributed_touch_time Thời gian tiếp xúc được phân bổ  
attributed_touch_time_selected_timezone Múi giờ thời gian tương tác được phân bổ đã chọn API Push cụ thể
attributed_touch_type Loại tiếp xúc được phân bổ  
bundle_id ID gói  
chiến dịch Chiến dịch  
nhà cung cấp dịch vụ nhà cung cấp dịch vụ  
thành phố thành phố  
contributor_1_af_prt Đối tác Người đóng góp 1  
contributor_1_campaign Chiến dịch Người đóng góp 1  
contributor_1_match_type Loại so khớp Người đóng góp 1  
contributor_1_media_source Nguồn phương tiện Người đóng góp 1  
contributor_1_touch_time Thời gian tương tác Người đóng góp 1  
contributor_1_touch_type Loại tương tác Người đóng góp 1  
contributor_2_af_prt Đối tác Người đóng góp 2  
contributor_2_campaign Chiến dịch Người đóng góp 2  
contributor_2_match_type Loại so khớp Người đóng góp 2  
contributor_2_media_source Nguồn phương tiện Người đóng góp 2  
contributor_2_touch_time Thời gian tương tác Người đóng góp 2  
contributor_2_touch_type Loại tương tác Người đóng góp 2  
contributor_3_af_prt Đối tác Người đóng góp 3  
contributor_3_campaign Chiến dịch Người đóng góp 3  
contributor_3_match_type Loại so khớp Người đóng góp 3  
contributor_3_media_source Nguồn phương tiện Người đóng góp 3  
contributor_3_touch_time Thời gian tương tác Người đóng góp 3  
contributor_3_touch_type Loại tương tác Người đóng góp 3  
cost_in_selected_currency Chi phí bằng loại tiền đã chọn API Push cụ thể
country_code Mã quốc gia  
custom_data Dữ liệu tùy chỉnh  
customer_user_id Customer User ID  
deeplink_url URL Liên kết sâu Có sẵn từ Q4/2019
device_category Danh mục thiết bị  
device_download_time Thời gian tải xuống của thiết bị  
device_type Loại thiết bị  
dma DMA  
download_time_selected_timezone Múi giờ thời gian tải xuống đã chọn API Push cụ thể
event_name Tên của sự kiện  
event_revenue Doanh thu sự kiện  
event_revenue_currency Tiền tệ doanh thu sự kiện  
event_revenue_usd Doanh thu sự kiện USD  
event_source Nguồn sự kiện  
event_time Thời gian sự kiện  
event_time_selected_timezone Múi giờ thời gian sự kiện đã chọn API Push cụ thể
event_value Giá trị của sự kiện  
gp_broadcast_referrer Liên kết giới thiệu GP Broadcast  
gp_click_time Thời gian nhấp Google Play  
gp_install_begin Thời gian bắt đầu cài đặt Google Play  
gp_referrer Liên kết giới thiệu Google Play  
http_referrer Liên kết giới thiệu HTTP  
idfa idfa  
idfv IDFV  
imei imei  
install_app_store Cài đặt App Store  
install_time Thời gian cài đặt  
install_time_selected_timezone Múi giờ thời gian cài đặt đã chọn API Push cụ thể
ip ip  
is_LAT Is LAT Có sẵn từ Q4/2019
is_primary_attribution Là phân bổ chính  
is_receipt_validated Biên nhận đã được xác nhận chưa  
is_retargeting Đang nhắm mục tiêu lại  
keyword_id ID từ khóa Có sẵn từ Q4/2019
keyword_match_type Loại so khớp từ khóa  
language ngôn ngữ  
match_type Loại so khớp  
media_source Nguồn truyền thông  
network_account_id ID tài khoản mạng  
OAID OAID Có sẵn từ Q4/2019
người điều hành người điều hành  
original_url URL gốc  
os_version Phiên bản hệ điều hành  
nền tảng nền tảng  
postal_code Mã bưu chính  
vùng Vùng  
retargeting_conversion_type Loại lượt chuyển đổi nhắm mục tiêu lại  
revenue_in_selected_currency Doanh thu bằng loại tiền đã chọn API Push cụ thể
sdk_version Phiên bản SDK  
selected_currency Tiền tệ đã chọn API Push cụ thể
múi_giờ_đã_chọn Múi giờ đã chọn API Push cụ thể
Bang Bang  
store_reinstall (False=Tải về, True=Tải về lại) Lưu trữ lượt cài đặt lại Có sẵn từ Q4/2019
user_agent Tác nhân người dùng  
wifi wifi  

Khắc phục sự cố, hạn chế & đặc điểm

Duplication of retargeting events

In some cases, retargeting events are duplicated. This occurs when an in-app purchase event takes place as a result of a retargeting campaign during the UA re-engagement window.

In this case, two attribution events are generated to attribute the revenue to the media source that brought the install and the media source that brought the re-engagement. 

You will only get two Push API's if you have enabled Push APIs for both

  • install in-app events
  • retargeting in-app events

 Ví dụ

  • A user installs example_app, which is attributed to ua_network
  • Later the user re-engages with example_app's retargeting campaign on retar_network and makes a purchase.

The event is sent twice with the following details:

Các trường API duy nhất
Loại sự kiện Media source is_retargeting re_targeting conversion_type
Không tự nhiên ua_network SAI null (no value)
Tái xác định mục tiêu  retar_network True Thu hút lại


How do I identify duplicate retargeting events?

Use the is_primary_attribution boolean field which indicates the primary and secondary media sources as follows. 

  • In UA campaigns the value can only be true because the UA media source is the only media source.
  • In retargeting campaigns:
    • True: identifies the re-engagement media source 
    • False: identifies the original UA media source

This reason for this is as follows: If a user, as a result of a retargeting campaign,  engages with the campaign, a re-engagement window opens. The re-engagement media source is regarded as the primary media source when the re-engagement window is open. After the window closes, the original UA media source reverts to being primary. 

Missing Facebook data

By default, Facebook does not release raw user-level data, until you accept Facebook's Terms of Service.
By doing so, you enable the sending of user-level data of installs coming from Facebook, via Push API (and to other raw data resources, as well).

Thiếu tin nhắn đẩy và CloudFront

Bạn có đang sử dụng Amazon CloudFront làm điểm cuối của mình không? Nếu vậy, hãy kiểm tra xem CloudFront có từ chối thông báo với mã từ chối 421 hay không. Nếu đúng như vậy, hãy xem Chọn cách phục vụ yêu cầu HTTPS của CloudFront

Hạn chế & Đặc điểm

Các đặc điểm
Đặc điểm Nhận xét 
Mạng quảng cáo Không dành cho các mạng quảng cáo sử dụng. 
Đại lý Không dành cho các đại lý sử dụng
Múi giờ riêng cho ứng dụng Được hỗ trợ
Tiền tệ dành riêng cho ứng dụng  Được hỗ trợ
Hạn chế về kích thước Không áp dụng
Tự nhiên 
Không tự nhiên
Độ mới của dữ liệu Thời gian thực
Dữ liệu lịch sử Not supported. Event data is sent after configuring Push API. If you need historical raw data use Pull API. 
Team member access Team members can view Push API settings but aren't able to make changes. 
Bài viết này có hữu ích không?