การติดตั้งใช้งาน AFS ที่มาพร้อมเครื่องสำหรับ Android

นอกจากนี้ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google ยังรองรับสไตล์โฆษณาที่กำหนดเองในเครือข่ายการค้นหาอีกด้วย หากแอปของคุณ ใช้ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google อยู่แล้ว เราขอแนะนำให้ใช้ เวอร์ชัน AFSMA SDK แทน

หากคุณกำลังอัปเกรดเป็นรุ่น 19.0.0 หรือใหม่กว่าจาก 18.1.0 หรือเก่ากว่า โปรดดูที่ คำแนะนำในการย้ายข้อมูล

ข้อกำหนดเบื้องต้น

คู่มือการติดตั้งใช้งานนี้จะถือว่าคุณคุ้นเคยกับสิ่งต่อไปนี้

• โฆษณา Search ที่กําหนดเองของ AdSense ที่มีสไตล์โฆษณาที่กําหนดเอง
• การพัฒนาแอป Android

นำเข้า SDK เนทีฟของ AFS

เพิ่ม SDK

หากต้องการเพิ่ม AFS Native SDK ลงในแอป ให้ทําดังนี้

เปิดไฟล์ build.gradle ภายในไดเรกทอรีโมดูลแอปพลิเคชัน เพิ่มกฎการสร้างใหม่ในส่วน dependencies สำหรับ SDK เวอร์ชันล่าสุด

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

ตรวจสอบว่า build.gradle ระดับบนสุดมีการอ้างอิงไปยัง google() ที่เก็บหรือไปที่ maven { url "https://maven.google.com" }

ทำตามวิธีการเหล่านี้ ให้รวมปลั๊กอินตัวจับคู่เวอร์ชันสแตนด์อโลนของ Google Play ไว้ในโครงการของคุณ การใช้ปลั๊กอินนี้ทำให้เกิดข้อผิดพลาดในการสร้าง Gradle เมื่อ AFS Native SDK คือ ใช้กับบริการ Google Play เวอร์ชันที่เข้ากันไม่ได้ แทนที่จะอนุญาต แอปที่สร้างแต่อาจทำให้รันไทม์ขัดข้อง หรือใช้ failOnVersionConflict() ResolutionStrategy ในโปรเจ็กต์ของคุณเพื่อทำให้เกิดข้อผิดพลาดในการสร้างเมื่อ Google Play เวอร์ชันที่เข้ากันไม่ได้ ระบบจะใช้บริการในโปรเจ็กต์ของคุณ บันทึกการเปลี่ยนแปลงและคลิกซิงค์โปรเจ็กต์กับไฟล์ Gradle แถบเครื่องมือ

ใช้ AndroidX แทนไลบรารีการสนับสนุนของ Android

ตั้งแต่ SDK เวอร์ชัน 17.0.0 เป็นต้นไป แอปของคุณต้องใช้ไลบรารี Jetpack (AndroidX) แทนไลบรารีสนับสนุนของ Android ข้อกำหนดความเข้ากันได้

• ตั้งค่า com.android.tools.build:gradle เป็น v3.2.1 ขึ้นไป
• ตั้งค่า compileSdkVersion เป็น 28 ขึ้นไป
• อัปเดตแอปเพื่อใช้ Jetpack (AndroidX) โดยทําตามวิธีการในหัวข้อการย้ายข้อมูลไปยัง AndroidX

ชั้นเรียน

ในการแสดงโฆษณาเนทีฟ AFS ในแอปของคุณ ให้ใช้คลาสต่อไปนี้

SearchAdController

• คลาสนี้มีหน้าที่ในการขอโฆษณา การแคช และแบบอะซิงโครนัส ดึงโฆษณา และแสดงผลโฆษณา
• บริบทโฆษณาแต่ละรายการต้องมี SearchAdController แยกกัน เช่น หากคุณ มีหน้าจอที่แสดงโฆษณาอยู่ข้างๆ รายการผลการค้นหา ซึ่งแสดงโฆษณาควบคู่ไปกับรายละเอียดของผลิตภัณฑ์ที่เฉพาะเจาะจง สร้างอินสแตนซ์ SearchAdController แยกกัน 2 รายการ โดยแต่ละรายการมีไว้สำหรับแต่ละกรณี
• ตัวสร้างต้องระบุรหัสพร็อพเพอร์ตี้ของเว็บ (รหัสผู้เผยแพร่โฆษณา), รหัสสไตล์ที่จะใช้กับโฆษณาที่แสดง และ SearchAdOptions Context ที่ระบุไว้ในเครื่องมือสร้าง ต้องเป็น Activity ที่มี SearchAdController และตำแหน่งของคุณ จะวางโฆษณา View
• เรียกใช้ loadAds เพื่อระบุการค้นหาผู้ใช้ใหม่ และเริ่มโฆษณาแบบไม่พร้อมกัน อีกครั้ง ระบบจะล้างโฆษณาที่โหลดจากการเรียก loadAds ก่อนหน้านี้ออกจากแคชโฆษณาภายในเมื่อมีการทำคําเรียกใหม่
• สร้าง View ด้วย createAdView เพื่อแสดงครีเอทีฟโฆษณา
• เมื่อโฆษณาโหลดแล้ว ให้เรียกใช้ populateAdView ด้วย View ที่สร้างขึ้นก่อนหน้านี้ ด้วย createAdView เพื่อแสดงผลโฆษณาที่แคชไว้ใน View นั้น นอกจาก View ที่จะเติมข้อมูล ให้ระบุ adKey ซึ่งเป็นสตริงที่กำหนดเองให้กับ ระบุโฆษณาได้โดยไม่ซ้ำกัน ซึ่งจะเชื่อมโยงครีเอทีฟโฆษณาที่เฉพาะเจาะจงซึ่งแสดงผลจากแคชกับ adKey นั้น ดังนั้นเมื่อมีการนํา adKey เดียวกันไปเรียกใช้ populateAdView ในอนาคต ระบบจะแสดงโฆษณาเดียวกัน ตัวอย่างเช่น หากเรียกใช้ populateAdView เป็นครั้งแรกด้วย adKey="keyA" และแสดงผลโฆษณารองเท้าเดินป่า การเรียกใช้ populateAdView ด้วย adKey="keyA" แต่ละครั้งต่อจากนั้นจะแสดงโฆษณารองเท้าเดินป่าเดียวกัน (กำลังโทรใหม่เพื่อ loadAds จะล้างโฆษณาที่แคชไว้และคีย์โฆษณาที่เกี่ยวข้องทั้งหมด)

SearchAdOptions

• ส่งออบเจ็กต์นี้ไปยังคอนสตรัคเตอร์ SearchAdController เพื่อปรับแต่งวิธีขอและแสดงโฆษณา โทรหา build() บน SearchAdOptions.Builder ไปยัง สร้างออบเจ็กต์ SearchAdOptions

View

• สร้างออบเจ็กต์ View เพื่อระงับโฆษณาโดยเรียกใช้ createAdView() ใน SearchAdController แสดงโฆษณาสูงสุดครั้งละ 1 รายการ แต่ View รายการเดียวกันสามารถ เพื่อนำไปแสดงใหม่ในตำแหน่งต่างๆ ได้ด้วย

SearchAdRequest

• เรียกใช้เมธอด loadAds ใน SearchAdController ด้วย SearchAdRequest เพื่อเริ่มคำขอโฆษณาแบบอะซิงโครนัส โทรหา build() บน SearchAdRequest.Builder เพื่อสร้างออบเจ็กต์ SearchAdRequest

AdListener

• ใช้อินเทอร์เฟซนี้และส่งไปยังเครื่องมือสร้าง SearchAdController ในการลงทะเบียน Callback สำหรับหลายๆ รัฐ
• หมายเหตุ: ระบบจะไม่เรียกการโทรกลับ AdListener รายการสำหรับคำขอที่ยกเลิก (การโทร ไปยัง loadAds ที่ถูกจองไว้โดยการโทรอีกครั้งถึง loadAds ก่อนการโทรครั้งแรก การโทรได้รับการแก้ไขแล้ว)

ตัวอย่างการใช้งาน

ตัวอย่างด้านล่างแสดงการสร้าง SearchAdController ในตัวอย่าง 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);
}

เมื่อผู้ใช้เริ่มการค้นหา ให้สร้าง SearchAdRequest และเรียกใช้ loadAds ใน SearchAdController เพื่อเริ่มคำขอโฆษณาแบบไม่พร้อมกัน

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

ใช้การเรียกกลับ onAdLoaded เพื่อแสดงโฆษณาที่โหลดลงในมุมมองโฆษณา

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");
}

โฆษณาที่เกี่ยวข้องกับคำค้นหาดังกล่าวจะปรากฏใน adView

การตรวจสอบข้อผิดพลาด

SearchAdController ต้องใช้ออบเจ็กต์ AdListener ที่มีเมธอด onAdLoaded() เพื่อแจ้งให้แอปทราบว่าโฆษณาพร้อมแสดงแล้ว คุณควรใช้ ใช้เมธอด onAdFailedToLoad() เพื่อให้คุณตรวจหาและแก้ไขข้อผิดพลาดได้ ตัวอย่างเช่น คุณอาจใช้ AdListener ต่อไปนี้เพื่อแก้ไขข้อบกพร่อง การใช้งาน:

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);
    }
};

ค่าคงที่ที่ใช้ในonAdFailedToLoad()เมธอดการเรียกกลับ จะกําหนดไว้ใน AdListener