Trang này được dịch bởi Cloud Translation API.

Triển khai gốc AFS dành cho Android

SDK quảng cáo trên thiết bị di động của Google cũng hỗ trợ các kiểu quảng cáo đi kèm kết quả tìm kiếm tùy chỉnh. Nếu ứng dụng của bạn đã sử dụng SDK quảng cáo trên thiết bị di động của Google, chúng tôi khuyên bạn nên sử dụng Phiên bản AFSMA SDK thay thế.

Nếu bạn đang nâng cấp lên phiên bản 19.0.0 trở lên từ 18.1.0 trở xuống, vui lòng xem hướng dẫn di chuyển của chúng tôi.

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

Hướng dẫn triển khai này giả định bạn đã quen thuộc với những điều sau:

Quảng cáo tìm kiếm tuỳ chỉnh AdSense với các kiểu tìm kiếm tuỳ chỉnh
Phát triển ứng dụng Android

Nhập SDK gốc AFS

Thêm SDK

Để thêm SDK gốc của AFS vào ứng dụng của bạn, hãy làm như sau:

Mở tệp build.gradle bên trong thư mục mô-đun ứng dụng của bạn. Thêm quy tắc bản dựng mới trong dependencies cho phiên bản SDK mới nhất:

dependencies {
  implementation 'com.google.android.gms:play-services-afs-native:19.1.0'
}

Đảm bảo rằng build.gradle cấp cao nhất của bạn chứa tham chiếu đến google() repo hoặc maven { url "https://maven.google.com" }.

Làm theo các hướng dẫn này để đưa Trình bổ trợ Trình khớp phiên bản độc lập của Google Play vào dự án của bạn. Việc áp dụng trình bổ trợ này sẽ gây ra lỗi bản dựng gradle khi SDK gốc AFS là được sử dụng với phiên bản Dịch vụ Google Play không tương thích thay vì cho phép tạo ứng dụng nhưng có thể gây ra sự cố trong thời gian chạy. Hoặc, áp dụng failOnVersionConflict() ResolutionStrategy dự án của bạn gây ra lỗi bản dựng khi các phiên bản Google Play không tương thích Các dịch vụ được sử dụng trong dự án của bạn. Lưu các thay đổi rồi nhấp vào Sync Project with Gradle Files (Đồng bộ hoá dự án với tệp Gradle) trong thanh công cụ.

Sử dụng AndroidX thay vì Thư viện hỗ trợ Android

Bắt đầu từ phiên bản 17.0.0 của SDK, ứng dụng của bạn phải sử dụng Jetpack (AndroidX) Thư viện thay vì Thư viện hỗ trợ Android. Yêu cầu về khả năng tương thích:

Thiết lập com.android.tools.build:gradle thành phiên bản 3.2.1 trở lên.
Đặt compileSdkVersion thành 28 trở lên.
Cập nhật ứng dụng để sử dụng Jetpack (AndroidX); làm theo hướng dẫn trong Di chuyển sang AndroidX.

Lớp

Để phân phát quảng cáo gốc AFS trong ứng dụng của bạn, hãy triển khai các lớp sau:

SearchAdController

Lớp này chịu trách nhiệm yêu cầu không đồng bộ quảng cáo, lưu vào bộ nhớ đệm và truy xuất quảng cáo và hiển thị quảng cáo.
Mỗi ngữ cảnh quảng cáo cần một SearchAdController riêng biệt; ví dụ: nếu bạn có màn hình hiển thị quảng cáo bên cạnh danh sách kết quả tìm kiếm và màn hình hiển thị quảng cáo cùng với thông tin chi tiết về một sản phẩm cụ thể, thì bạn nên tạo hai thực thể SearchAdController riêng biệt, mỗi thực thể cho một trường hợp.
Hàm khởi tạo cần được cung cấp mã thuộc tính web (mã nhà xuất bản), mã kiểu để áp dụng cho quảng cáo trả về và SearchAdOptions. Context được cung cấp trong hàm khởi tạo phải là Activity chứa SearchAdController và nơi bạn sẽ đặt quảng cáo View.
Gọi loadAds để cho biết hoạt động tìm kiếm của người dùng mới và bắt đầu quảng cáo không đồng bộ của bạn. Mọi quảng cáo được tải từ các cuộc gọi trước đó đến loadAds sẽ bị xoá khỏi bộ nhớ đệm quảng cáo nội bộ khi có lệnh gọi mới được thực hiện.
Tạo View bằng createAdView để hiển thị mẫu quảng cáo.
Sau khi quảng cáo tải xong, hãy gọi populateAdView bằng View đã tạo trước đó với createAdView để hiển thị một quảng cáo được lưu vào bộ nhớ đệm trong View đó. Ngoài View sẽ được điền sẵn, hãy cung cấp adKey (một chuỗi tuỳ ý) để xác định duy nhất quảng cáo. Điều này liên kết quảng cáo cụ thể được trả về từ bộ nhớ đệm có adKey đó, để khi cùng một adKey được chuyển vào lệnh gọi trong tương lai đến populateAdView, thì hệ thống sẽ trả về quảng cáo đó. Ví dụ: nếu populateAdView được gọi lần đầu tiên bằng adKey="keyA" và kết xuất một quảng cáo về giày đi bộ đường dài, mỗi lệnh gọi tiếp theo đến populateAdView với adKey="keyA" sẽ hiển thị cùng một quảng cáo cho giày đi bộ đường dài. (Thực hiện cuộc gọi mới đến loadAds sẽ xoá tất cả quảng cáo được lưu vào bộ nhớ đệm và khoá quảng cáo liên kết.)

SearchAdOptions

Truyền đối tượng này đến hàm khởi tạo SearchAdController để tuỳ chỉnh cách quảng cáo được yêu cầu và hiển thị. Gọi build() trên SearchAdOptions.Builder để tạo một đối tượng SearchAdOptions.

View

Tạo đối tượng View để giữ quảng cáo bằng cách gọi createAdView() trên SearchAdController. Hiển thị tối đa một quảng cáo tại một thời điểm, nhưng cùng một View có thể được tái chế để hiển thị các quảng cáo khác nhau theo thời gian.

SearchAdRequest

Gọi phương thức loadAds trên SearchAdController bằng SearchAdRequest để bắt đầu một yêu cầu quảng cáo không đồng bộ. Gọi build() trên SearchAdRequest.Builder để tạo một đối tượng SearchAdRequest.

AdListener

Triển khai và truyền giao diện này đến hàm khởi tạo SearchAdController để đăng ký lệnh gọi lại cho một số trạng thái.
Lưu ý: Các lệnh gọi lại AdListener sẽ không được gọi đối với yêu cầu đã bị huỷ (lệnh gọi với loadAds đã bị giành trước bởi một lệnh gọi khác đến loadAds trước lần gọi đầu tiên đã giải quyết cuộc gọi).

Cách triển khai mẫu

Ví dụ bên dưới minh hoạ việc tạo SearchAdController trong một mẫu Activity.

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

SearchAdController adController;
// adContainer where we will place our ads in this example.
ViewGroup adContainer;

protected void onCreate(Bundle bundle){
  super.onCreate(bundle);
  adContainer = (ViewGroup) findViewById(...);
  // Specify ad options (not required).
  SearchAdOptions.Builder adOptionsBuilder = new SearchAdOptions.Builder();
  adOptionsBuilder.setAdType(SearchAdOptions.AD_TYPE_TEXT);
  adOptionsBuilder.setPrefetch(true);
  adOptionsBuilder.setNumAdsRequested(3);
  // Provide a callback to trigger when ads are loaded.
  AdListener adListener = new AdListener() {
    public void onAdLoaded() {
      createAndShowAd();
    }
  };
  // Instantiate the SearchAdController.
  adController = new SearchAdController(this, "your-client-id", "your-style-id",
                                        adOptionsBuilder.build(), adListener);
}

Khi người dùng bắt đầu một truy vấn, hãy tạo một SearchAdRequest rồi gọi loadAds trên SearchAdController để bắt đầu một yêu cầu quảng cáo không đồng bộ.

// Create the request.
SearchAdRequest.Builder requestBuilder = new SearchAdRequest.Builder();
requestBuilder.setQuery("user query here");
// Load the ads.
adController.loadAds(requestBuilder.build());

Triển khai lệnh gọi lại onAdLoaded để điền quảng cáo được tải vào chế độ xem quảng cáo.

private void createAndShowAd() {
  // Create a new view that will contain the ad.
  View adView = adController.createAdView();
  // Attach the new view to the view hierarchy.
  adContainer.addView(adView);
  // Display the ad inside the adView. We need to provide an adKey to
  // indicate which ad is to be displayed in the adView. In this example, 
  // since we only have one ad, we can provide any constant string. However, 
  // if you intend to display multiple ads, each ad you wish to display
  // should be given a unique adKey of your choosing.
  adController.populateAdView(adView, "demoAd");
}

Giờ đây, một quảng cáo liên quan đến cụm từ tìm kiếm đã cho sẽ xuất hiện trong adView.

Điều tra lỗi

SearchAdController yêu cầu đối tượng AdListener có onAdLoaded() để thông báo cho ứng dụng rằng quảng cáo đã sẵn sàng hiển thị. Bạn cũng nên hãy triển khai phương thức onAdFailedToLoad() để bạn có thể phát hiện và sửa lỗi. Ví dụ: bạn có thể sử dụng AdListener sau để gỡ lỗi triển khai:

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

    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example).
        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.
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
};

Hằng số được dùng trong phương thức gọi lại onAdFailedToLoad() được xác định trong AdListener.