Sử dụng dữ liệu hợp nhất API Pull

Khái quát: Sử dụng URI để nhận báo cáo hợp nhất AppsFlyer của bạn dưới dạng tệp tin CSV.

PullAPIAverage_us-en.png

 Bạn đang tìm kiếm dữ liệu thô API Pull?

Dữ liệu thô API Pull

Đặc điểm của dữ liệu hợp nhất API Pull

  • Báo cáo trả về dưới dạng tệp tin CSV.
  • Tốc độ cập nhật dữ liệu giống như báo cáo tương đương trên trang Dữ liệu xuất.
  • Lọc theo các tùy chọn có sẵn: Nguồn truyền thông và phạm vi ngày.
  • Các khả năng khác trong API Pull là:
    • Có khả năng lọc theo kiểu tiếp xúc phân bổ
    • Có thể lựa chọn múi giờ 
  • API Pull phù hợp cho các thành viên nhóm và nhà phát triển BI sử dụng;
    • Thành viên nhóm lấy báo cáo bằng cách dán URI vào trình duyệt của họ. Các mẫu URI có sẵn trong Bảng điều khiển. Đi đến Tích hợp > Truy cập API.
    • Nhà phát triển BI lấy báo cáo bằng cách nhúng các URI vào tập lệnh. 

Ví dụ về mẫu URITemplateURL_us-en.jpg

danh mục  UA Nhắm mục tiêu lại* Protect360
Đối tác (nguồn truyền thông)

Đối tác theo ngày

Hằng ngày

Địa lý

Địa lý theo ngày

* Đối với các báo cáo nhắm mục tiêu lại, hãy thêm &reattr=true vào URI. 

Báo cáo hiệu suất hợp nhất có sẵn thông qua API Pull

 Bài viết liên quan:

Bảng thuật ngữ

Thuật ngữ Mô tả
API Pull

Giải pháp tải xuống báo cáo CSV bằng URI.

Lệnh gọi API hoặc lệnh gọi 

Gửi URI tới AppsFlyer bằng cách dán URI vào thanh địa chỉ của trình duyệt hoặc sử dụng tập lệnh.

URI
  • Mã định danh tài nguyên đồng nhất đôi khi tương tự như địa chỉ web (URL) có chứa đặc điểm kỹ thuật báo cáo.
  • URI mẫu có sẵn trên trang API trong Bảng điều khiển.

Hướng dẫn cho các thành viên nhóm

Giới thiệu về mẫu URI

  • Các mẫu URI có sẵn trong bảng điều khiển được điền bằng ID ứng dụng và loại báo cáo.
  • Các mẫu này có phần giữ chỗ cho mã thông báo API V1.0 và ngày bắt đầu/kết thúc mà bạn cần chỉnh sửa.
  • Phần của URI ở bên phải dấu chấm hỏi (?) chứa thông số. Mỗi thông số bắt đầu bằng ký hiệu (&). Các thông số được sử dụng để đặt bộ lọc, chỉ định các trường sẽ được thêm vào, tiền tệ và múi giờ. Ví dụ: trong các báo cáo hợp nhất để giới hạn (lọc theo) một nguồn truyền thông cụ thể, hãy sử dụng thông số media_source: &media_source=facebook
  • Để hiểu rõ hơn về API Pull, hãy hoàn thành hướng dẫn sau.

Nhận hướng dẫn báo cáo API Pull lần đầu của bạn

Trước khi bạn bắt đầu:

Để tải xuống báo cáo từ bảng điều khiển: 

  1. Đi đến Tích hợp > Truy cập API.
    Trang truy cập API sẽ mở ra. PullAPIPartnersReport_us-en.jpg
  2. Chọn một loại báo cáo. Ví dụ: Báo cáo hiệu suấtBáo cáo đối tác hàng ngày. 
    Mẫu URI sẽ hiển thị. 
  3. Sao chép URI bằng cách nhấp vào URI đó.
  4. Mở một tab mới trong trình duyệt của bạn rồi dán URI.
  5. Chỉnh sửa URI:
    1. Thay phần giữ chỗ mã thông báo bằng mã thông báo API Pull do quản trị viên cung cấp.
      Thay phần giữ chỗ mã thông báo sao cho &api_token=12345678-1234-1234-1234-123456789012 Lưu ý! Không có dấu cách hoặc dấu câu khác. 
    2. Thay phần giữ chỗ from/to bằng ngày tháng.
      Ví dụ: &from=2020-01-20&to=2020-01-31 Lưu ý! Không có dấu cách. Không được xóa &. 
  6. Nhấp vào <Enter> để gửi lệnh gọi API. 
    Báo cáo được tải xuống.
    Các thông số bổ sung có thể được đặt để tùy chỉnh báo cáo, ví dụ: chọn một nguồn truyền thông cụ thể, để trả về dữ liệu nhắm mục tiêu lại, v.v. Phần tiếp theo gồm danh sách các thông số khả dụng. 

Thông số dữ liệu hợp nhất API Pull

URI báo cáo hợp nhất và thông số

Các thông số bắt buộc của URI hợp nhất 
Tham số Mô tả
api_token Mã thông báo API V1.0. Trong ví dụ, các lệnh gọi này được hiển thị là: <API TOKEN HERE>. 
từ
  • Phạm vi ngày bao gồm thông số fromvà to . Phạm vi là phạm vi ngày LTV (cài đặt).
  • Định dạng: yyyy-mm-dd, 
  • Ví dụ: 2010-01-01 hoặc 2010-01-01
tới Ngày kết thúc. Đối với from
Thông số hiển thị và lọc dữ liệu hợp nhất tùy chọn không bao gồm các báo cáo Protect360
Tham số Mô tả
media_source

Sử dụng để giới hạn (lọc) cho một nguồn truyền thông cụ thể.

  • Ví dụ:media_source=facebook
attribution_touch_type

Đặt thông số này như trong ví dụ minh họa để lấy KPI phân bổ lượt xem hết (VTA). 

Ví dụ: attribution_touch_type=impression

tiền tệ

Đơn vị tiền tệ của doanh thu và chi phí.

Báo cáo API Pull hợp nhất luôn sử dụng đơn vị tiền tệ dành riêng cho ứng dụng.

reattr

Nhận dữ liệu lượt chuyển đổi nhắm mục tiêu lại.

  • [Mặc định] Nếu sai, sẽ trả về các chiến dịch dữ liệu thu hút người dùng (UA).
  • Nếu là true, lượt chuyển đổi nhắm mục tiêu lại sẽ được trả về.
  • Ví dụ:reattr=true
Múi giờ

[Mặc định] Dữ liệu trả về bằng cách sử dụng UTC.

  • URI mẫu được điền bằng thông số múi giờ được đặt thành múi giờ dành riêng cho ứng dụng. 
  • [Mặc định] Nếu thông số không được gửi đi, dữ liệu sẽ trả về sử dụng UTC.
  • Nếu bạn gửi timezone=[Joda-Time], dữ liệu sẽ trả về sử dụng múi giờ dành riêng cho ứng dụng.

Lưu ý về việc chọn múi giờ

  • 1. Định dạng múi giờ Joda-Time tính đến thời gian tiết kiệm ánh sáng ban ngày.
  • Giá trị Joda-Time phải giống hệt với giá trị trên trang cài đặt ứng dụng. Ví dụ, nếu múi giờ cài đặt là Paris, thì giá trị múi giờ trong URL của API Pull phải là timezone=Europe%2fParis.
  • Chỉ có thể kéo dữ liệu trong múi giờ đã chọn kể từ ngày thiết lập múi giờ. Mọi dữ liệu trước ngày thay đổi đều sử dụng UTC làm múi giờ. 

Báo cáo đã lọc của Google Ads

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=googleadwords_int

Báo cáo đã lọc của Facebook

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=facebook
Các thông số tùy chọn cho các báo cáo Protect360
Tham số Mô tả
URI
  • Nhận URI Protect360 từ bảng điều khiển.
  • Sửa đổi URI như được mô tả tại đây. 
PID

Để lọc báo cáo theo một nguồn truyền thông cụ thể, hãy sử dụng thông số pid. Ví dụ: để lấy dữ liệu của abc_net, pid=abc_net.

Múi giờ

Chọn múi giờ được sử dụng để trả về dữ liệu.

Nếu múi giờ không được gửi, dữ liệu được trả về sử dụng UTC.

Mẫu bao gồm thông số múi giờ

Ví dụ: timezone=preferred: Sử dụng để lấy dữ liệu bằng cách sử dụng múi giờ dành riêng cho ứng dụng .

KPI

Tham số Protect360 ở API kéo và API chính là giống nhau. 

KPI phân bổ lượt xem hết (VTA)

  • Để lấy KPI VTA, hãy thêm thông số attribution_touch_type=impression vào URI báo cáo hợp nhất API Pull được nêu chi tiết trong ví dụ.
  • Bạn có thể sử dụng thông số cùng bất kỳ báo cáo hợp nhất nào có sẵn. Chỉ cần sao chép URI từ giao diện người dùng và nối thêm thông số.
  • Bạn cũng có thể thêm thông số &media_source để giới hạn báo cáo chỉ một nguồn phương tiện cụ thể như được mô tả trong ví dụ sau.
  • Một số KPI VTA, như lượt nhấp, lượt hiển thị và API chi phí, không có giá trị được liên kết với chúng và thay vào đó sẽ hiển thị giá trị N/A. 
Ví dụ: URI ví dụ
Chỉ VTA  https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression

VTA và nguồn truyền thông

https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network

API Pull dành cho nhà phát triển

Nguyên tắc thực hiện

Điều kiện tiên quyết:

Làm quen với hướng dẫn API Pull dành cho các thành viên nhóm.

Cân nhắc:

  • Đối với mỗi loại báo cáo có sẵn, sẽ có một URI mẫu trong bảng điều khiển. Đi đến Tích hợp > Truy cập API.
  • Bạn sửa đổi mẫu để có được dữ liệu bạn cần. Ví dụ: bằng cách đặt phạm vi ngày và bộ lọc theo thông số.
  • Các thông số cho dữ liệu thô và báo cáo dữ liệu hợp nhất sẽ khác nhau và được trình bày chi tiết trong các phần báo cáo.
Thông tin cơ bản về API Pull
Đường dẫn

https://hq.appsflyer.com/export/app_id/report_type/v5

Thông số đường dẫn

app_id

  • Mã định danh ứng dụng như được tìm thấy trong AppsFlyer.
  • Chèn ID ứng dụng chính xác như được tìm thấy trong AppsFlyer.
  • Thêm tiền tố id cho ứng dụng iOS

report_type 

  • Xác định loại báo cáo. Danh sách các báo cáo và URI liên quan nằm trong bảng điều khiển. Đi đến Tích hợp > Truy cập API. 
Phương thức HTTP

GET

Các thông số truy vấn bắt buộc
Tham số Mô tả
URI ví dụ

GET 'https://hq.appsflyer.com/export/app_id/installs_report/v5? from=2020-01-01?&to=2020-01-10&api_token=api_token&currency=preferred

api_token

api_token: Mã thông báo API Pull để xác thực

Các thông số khác

Các thông số khác nhau tùy thuộc vào 

 Ví dụ

Ví dụ về lệnh gọi URI bao gồm các thông số bổ sung: 

https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
        api_token={Account owner API key should be used}&from=yyyy-mm-dd
&to=yyyy-mm-dd&additional_fields=keyword_id,store_reinstall,
deeplink_url,oaid,install_app_store,contributor1_match_type,
contributor2_match_type,contributor3_match_type,match_type

Các tập lệnh ví dụ

Tích hợp API Pull vào các tập lệnh để truy xuất dữ liệu.

  • Khi cần, hãy chỉnh sửa tập lệnh về loại báo cáo, phạm vi ngày và bộ lọc. 
  • Các ví dụ này sử dụng báo cáo lượt cài đặt.
JavaNode JSPythonC#PHP
import okhttp3.*;

import java.io.BufferedWriter;
import java.io.FileWriter;

import java.util.concurrent.TimeUnit;

public class PullApi {
  public static void main(String[] args){

    String appID = "<APP_ID>";
    String reportType = "<REPORT_TYPE>";
    String apiToken = "<API_TOKEN>";
    String from = "<FROM_DATE>";
    String to = "<TO_DATE>";
    String requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;

    OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)

        .build();

    Request request = new Request.Builder()
        .url(requestUrl)
        .addHeader("Accept", "text/csv")
        .build();

    try {
      Response response = client.newCall(request).execute();

      if(response.code() != 200) {
        if(response.code() == 404) {
          System.out.println("There is a problem with the request URL. Please make sure it is correct");
        }
        else {
          assert response.body() != null;
          System.out.println("There was a problem retrieving the data: " + response.body().string());
        }
      } else {
        assert response.body() != null;
        String data = response.body().string();
        BufferedWriter writer;

        writer = new BufferedWriter(new FileWriter(appID + "-" + reportType + "-" + from + "-to-" + to + ".csv"));
        writer.write("");
        writer.write(data);
        writer.close();
      }
      System.exit(0);
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(1);
    }
  }
}

Thông tin Bổ sung

Sự khác nhau giữa API Pull V4 và V5. 

Dữ liệu thô: API V4 vẫn có sẵn để sử dụng. Không có thay đổi nào đối với định dạng và tiêu đề tệp tin.

Dữ liệu hợp nhất (V5):

Trong V5.0, sẽ có thêm các trường sau khi media_source=facebook:

  • ID Chiến dịch
  • Tên bộ quảng cáo
  • ID Bộ quảng cáo
  • Tên quảng cáo (nhóm quảng cáo)
  • Id quảng cáo (nhóm quảng cáo)

Đặc điểm và hạn chế

Đặc điểm
Đặc điểm Nhận xét 
Loại mã thông báo API bắt buộc AppsFlyerAdmin_us-en.pngMã thông báo V1.0
Truy cập mạng quảng cáo N
Truy cập đại lý Y
Tính minh bạch của agency Y
Tiền tệ dành riêng cho ứng dụng  Y
Múi giờ riêng cho ứng dụng Y
Độ mới của dữ liệu Thời gian thực
Dữ liệu lịch sử Y
Dữ liệu không tự nhiên Y
Dữ liệu tự nhiên Y
Giới hạn lưu lượng

Mức giới hạn

Hạn chế về kích thước
  • Các lệnh gọi API trả về số hàng tối đa là 200K.
  • Nếu một báo cáo có đúng 200K hàng, thì giả sử là có các hàng bị thiếu.
  • Thực hiện nhiều lệnh gọi API, sử dụng thông số bắt đầu/kết thúc bao gồm cả thời gian trong ngày.  
Thay đổi tên chiến dịch Báo cáo API Pull không hỗ trợ thay đổi tên chiến dịch

Mã lỗi API và khắc phục sự cố

Mã lỗi và giải pháp
Trạng thái Dấu hiệu/thông báo Giải pháp
OK 200 Tệp tin CSV trống
  • addtional_fieldsxuất hiện nhiều lần trong URI
  • Đảm bảo rằng cả ngày bắt đầu và ngày kết thúc đều có định dạng yyyy-mm-dd (năm-tháng-ngày)
OK

200

 

Không tìm thấy mã thông báo API nào trong URI

Yêu cầu không đạt

400

Thời gian xem lại lịch sử báo cáo thô được giới hạn trong 90 ngày

Sử dụng thông số to và from để giới hạn phạm vi ngày trong 3 tháng trở xuống.

Yêu cầu không đạt

400

Đã đạt đến giới hạn lệnh gọi API của bạn cho loại báo cáo nhất định

-
Không được phép

401

Mã thông báo API được cấp không hợp lệ 

Yêu cầu quản trị viên cấp mã thông báo hiện tại.
Không được phép

401

Tài khoản có thể bị tạm ngừng hoạt động

Đăng nhập vào bảng điều khiển và kiểm tra trạng thái của tài khoản. 

Không tìm thấy

404

Xuất hiện trang thông báo lỗi 404 của AppsFlyer

  • Đảm bảo rằng id ứng dụng là chính xác. Ứng dụng iOS phải bắt đầu bằng id.
  • Mã thông báo không khớp với ứng dụng. Bạn có đang sử dụng đúng mã thông báo không? 
Bài viết này có hữu ích không?