Triển khai AFS dành cho ứng dụng di động (AFSMA) cho Android

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

Hướng dẫn triển khai này giả định bạn đã quen với các yêu cầu sau:

Lớp

Để phân phát quảng cáo AFSMA (còn gọi là quảng cáo tìm kiếm theo chiều cao động) trong ứng dụng, hãy triển khai các lớp sau:

SearchAdView

  • Lớp này kế thừa từ lớp ViewGroup của Android và hiển thị quảng cáo AFSMA. SearchAdView đưa ra yêu cầu về một quảng cáo có DynamicHeightSearchAdRequest và hiển thị các quảng cáo được trả về. Bạn phải thêm SearchAdView vào bất kỳ nhóm khung hiển thị hiện có nào của ứng dụng.
  • Bạn phải tạo thực thể cho SearchAdView với ngữ cảnh mà SearchAdView đang chạy, thường là Activity.
  • Sau khi bạn đã tạo SearchAdView, bạn phải gọi phương thức setAdSize() bằng AdSize.SEARCH để yêu cầu quảng cáo AFSMA. Các giá trị enum khác sẽ yêu cầu quảng cáo không tương thích với AFS dành cho ứng dụng di động.
  • Gọi phương thức setAdUnitId() trên đối tượng này bằng mã thuộc tính.

DynamicHeightSearchAdRequest.Builder

  • Lớp này đóng gói các thông số yêu cầu quảng cáo. Điều này tương tự như việc đặt các thông số trong đối tượng yêu cầu quảng cáo JavaScript (tuỳ chọn trang, lựa chọn đơn vị) cho AFS trên web dành cho máy tính và web dành cho thiết bị di động.
  • Đặt các tham số bằng phương thức setter thích hợp (nói cách khác, hãy gọi setQuery() để đặt tham số truy vấn).

Cách triển khai mẫu

Ví dụ bên dưới minh hoạ cách sử dụng Activity để tạo SearchAdView dưới dạng khung hiển thị phụ của ViewGroup. Để yêu cầu quảng cáo AFSMA đúng cách, đối tượng SearchAdView phải gọi phương thức setAdSize() bằng AdSize.SEARCH.

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

// Create the SearchAdView
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// Add searchAdView to parent view group
...

Trong cùng một Activity, hãy tạo một DynamicHeightSearchAdRequest.Builder mô tả các tham số của quảng cáo sẽ hiển thị trong SearchAdView. Quảng cáo AFSMA được định cấu hình giống như Quảng cáo tìm kiếm tuỳ chỉnh AFS; hãy xem Tài liệu tham khảo về Quảng cáo tìm kiếm tuỳ chỉnh AFS để biết thông tin chi tiết.

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");
builder.setNumber(2);

// Replace with the ID of a style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);

Bạn có thể sử dụng các lựa chọn tuỳ chỉnh khác bằng cách đặt thuộc tính bổ sung cho đối tượng DynamicHeightSearchAdRequest.Builder.

Để tạo một yêu cầu quảng cáo, hãy gọi phương thức loadAd() bằng đối tượng DynamicHeightSearchAdRequest.Builder từ đối tượng SearchAdView:

searchAdView.loadAd(builder.build());

Tuỳ chọn nâng cao

Bạn có thể thiết lập hầu hết các tham số yêu cầu quảng cáo thông qua các phương thức setter trên đối tượng DynamicHeightSearchAdRequest.Builder. Bạn có thể đặt bất kỳ tham số nào không có phương thức setter trong DynamicHeightSearchAdRequest.Builder bằng cách sử dụng các cặp khoá-giá trị với phương thức setAdvancedOptionValue(). Hãy xem Tài liệu tham khảo về Quảng cáo tìm kiếm tuỳ chỉnh AFS để biết danh sách đầy đủ các chế độ cài đặt có thể đặt bằng phương thức setAdvancedOptionValue().

Tham số khoá phải có tiền tố là "csa_" để thuộc tính được đặt chính xác. 

// Advanced customization options (set using key-value pair)

// Set a parameter (parameter_name) and its value (parameter_value)
// builder.setAdvancedOptionValue("csa_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

Nếu bạn sử dụng phương thức setter của một tham số và thiết lập bằng setAdvancedOptionValue, thì lệnh gọi thứ hai sẽ ghi đè giá trị của lệnh gọi đầu tiên.

Điều tra lỗi

SearchAdView (searchAdView ở đây) chứa phương thức setAdListener() để giúp bạn điều tra lỗi. Trong cùng một Activity:

searchAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Called when an ad is loaded
        super.onAdLoaded();
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        super.onAdLeftApplication();
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed
        super.onAdFailedToLoad(errorCode);
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
});

Các hằng số dùng trong phương thức gọi lại onAdFailedToLoad() được mô tả trong Tài liệu tham khảo API.

Chuẩn bị cho các yêu cầu công bố dữ liệu của Google Play

Vào tháng 5 năm 2021, Google Play đã ra mắt mục An toàn dữ liệu. Mục mới này là thông tin công bố của nhà phát triển về các phương pháp thu thập, chia sẻ và bảo mật dữ liệu của ứng dụng.

Trang này có thể giúp bạn đáp ứng các yêu cầu công bố dữ liệu này liên quan đến việc bạn sử dụng SDK gốc AFS (cũng áp dụng cho việc sử dụng AdSense cho Mua sắm). Trên trang này, bạn có thể tìm thấy thông tin về việc SDK của chúng tôi có xử lý dữ liệu của người dùng cuối hay không và cách xử lý dữ liệu này.

Chúng tôi luôn cố gắng minh bạch nhất có thể trong việc hỗ trợ bạn. Tuy nhiên, là nhà phát triển ứng dụng, bạn phải tự quyết định cách phản hồi biểu mẫu trong mục An toàn dữ liệu của Google Play liên quan đến phương pháp mà ứng dụng của bạn dùng để thu thập, chia sẻ và bảo mật dữ liệu của người dùng cuối.

Cách sử dụng thông tin trên trang này

Trang này chỉ liệt kê dữ liệu người dùng cuối mà phiên bản mới nhất của SDK thu thập.

Để hoàn tất yêu cầu công bố liên quan đến dữ liệu, bạn có thể tham khảo hướng dẫn về các loại dữ liệu của Android để xác định loại dữ liệu mô tả chính xác nhất dữ liệu được thu thập. Trong thông tin công bố liên quan đến dữ liệu, bạn nhớ đề cập đến cả cách ứng dụng cụ thể của bạn chia sẻ và sử dụng dữ liệu đã thu thập.

Loại dữ liệu mà SDK truy cập và thu thập

Gói:

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

Dữ liệu được thu thập tự động

SDK AFS sẽ tự động thu thập dữ liệu sau. Tất cả dữ liệu đều được chuyển từ thiết bị đến Google nhằm mục đích phân phát quảng cáo và tất cả dữ liệu đều được mã hoá trong quá trình chuyển. Thông tin cá nhân của người dùng không bao giờ được thu thập, trừ phi ứng dụng của bạn gửi đi truy vấn của người dùng.

Dữ liệu Dữ liệu này được thu thập cho các mục đích sau...
Địa chỉ IP Tóm tắt:
  • Phòng chống gian lận, đảm bảo tính bảo mật và tuân thủ pháp luật
  • Quảng cáo hoặc tiếp thị
  • Suy ra vị trí gần đúng
Chi tiết:
Địa chỉ IP được dùng để giám sát hành vi gian lận và sai trái cũng như để lấy thông tin vị trí ước chừng của người dùng.

Sau đó, hệ thống sử dụng vị trí ước chừng để đảm bảo quảng cáo được phân phát có thể tuân theo quy định của địa phương và để cung cấp quảng cáo có liên quan đến vị trí địa lý tương đối của người dùng.

Hoạt động trong ứng dụng
  • Lượt xem trang và lượt nhấn trong ứng dụng
  • Nhật ký tìm kiếm trong ứng dụng
 Tóm tắt:
  • Số liệu phân tích
  • Phòng chống gian lận, đảm bảo tính bảo mật và tuân thủ pháp luật
  • Quảng cáo hoặc tiếp thị
  • Hoạt động cá nhân hoá
Chi tiết:
Ứng dụng của bạn cung cấp cho chúng tôi cụm từ tìm kiếm của người dùng để chúng tôi trả về những quảng cáo Tìm kiếm có liên quan đến từ khoá. Chúng tôi đo lường lượt xem và lượt tương tác (lượt nhấn) với quảng cáo được trả về.
Chẩn đoán Tóm tắt:
  • Số liệu phân tích
Chi tiết:
SDK đo lường độ trễ hiển thị cho quảng cáo để có thể triển khai và đo lường những điểm cải tiến về sản phẩm. Chúng tôi cũng gửi báo cáo sự cố/lỗi và thỉnh thoảng thêm các công cụ đo lường khác khi cần để hiểu cách nhà xuất bản sử dụng chức năng này.
Mã nhận dạng thiết bị hoặc mã nhận dạng khác Tóm tắt:
  • Phòng chống gian lận, đảm bảo tính bảo mật và tuân thủ pháp luật
  • Quảng cáo hoặc tiếp thị
Chi tiết:
Mã thiết bị được dùng để giúp giám sát hành vi gian lận và sử dụng sai mục đích cũng như đo lường hiệu suất quảng cáo.