เริ่มต้นใช้งาน

PAL ช่วยให้คุณส่งสัญญาณโฆษณา Google ในคําขอโฆษณาและระหว่างการเล่นโฆษณาได้

คู่มือนี้ครอบคลุมการเพิ่ม Android PAL SDK ลงในแอป หากต้องการดูแอปตัวอย่างที่ใช้ PAL เพื่อสร้าง Nonce ให้ดาวน์โหลดตัวอย่าง Android จาก GitHub

เพิ่ม Android PAL SDK เป็นไลบรารี

ตั้งแต่เวอร์ชัน 18.0.0 เป็นต้นไป PAL SDK จะโฮสต์อยู่ในที่เก็บ Maven ของ Google และ สามารถเพิ่มลงในแอปได้ดังนี้

implementation 'com.google.android.gms:play-services-pal:22.1.0'
build.gradle

หรือจะดาวน์โหลด PAL SDK จากที่เก็บ Maven ของ Google แล้วเพิ่มลงในแอปด้วยตนเองก็ได้

สร้าง Nonce

Nonces คือสตริงที่เข้ารหัสเดียวที่ PAL สร้างขึ้นโดยใช้NonceLoader class PAL กำหนดให้คำขอสตรีมแต่ละรายการต้องมี ค่า Nonce ที่ไม่ซ้ำกัน อย่างไรก็ตาม คุณสามารถนำ Nonce กลับมาใช้ใหม่สำหรับคำขอโฆษณาหลายรายการ ในสตรีมเดียวกันได้ หากต้องการสร้าง Nonce โดยใช้ PAL SDK ให้ทำการเปลี่ยนแปลงต่อไปนี้เพื่อนำเข้าและตั้งค่า PAL รวมถึงสร้างฟังก์ชันเพื่อสร้าง Nonce

  1. นําเข้าและตั้งค่า PAL โดยทําดังนี้

    1. นำเข้าชั้นเรียน PAL

      import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;
import java.util.HashSet;
import java.util.Set;

      MainActivity.java

    2. สร้างตัวแปรส่วนตัวเพื่อจัดเก็บอินสแตนซ์ NonceLoader และ NonceManager 

      private NonceLoader nonceLoader;
private NonceManager nonceManager;
      MainActivity.java

    3. เริ่มต้นอินสแตนซ์ NonceLoader ด้วยอินสแตนซ์ ConsentSettings ในเมธอด onCreate

      @Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  // The default value for allowStorage() is false, but can be
  // changed once the appropriate consent has been gathered. The
  // getConsentToStorage() method is a placeholder for the publisher's own
  // method of obtaining user consent, either by integrating with a CMP or
  // based on other methods the publisher chooses to handle storage consent.
  boolean isStorageAllowed = getConsentToStorage();

  ConsentSettings consentSettings =
      ConsentSettings.builder().allowStorage(isStorageAllowed).build();

  // It is important to instantiate the NonceLoader as early as possible to
  // allow it to initialize and preload data for a faster experience when
  // loading the NonceManager. A new NonceLoader will need to be instantiated
  // if the ConsentSettings change for the user.
  nonceLoader = new NonceLoader(this, consentSettings);

  adClickButton = findViewById(R.id.send_click_button);

  logView = findViewById(R.id.log_view);
  logView.setMovementMethod(new ScrollingMovementMethod());
}

      MainActivity.java

    ในแอป ให้สร้างอินสแตนซ์ของคลาส NonceLoader 1 รายการสำหรับเซสชันของผู้ใช้แต่ละราย หากแอปมีหลายหน้าหรือโครงสร้างที่เทียบเท่า ให้สร้างอินสแตนซ์ NonceLoader ใหม่สำหรับแต่ละหน้าหรือเทียบเท่าหน้า การใช้NonceLoaderอินสแตนซ์เดียวกันจะช่วยให้ตัวเชื่อมโยงหน้าเว็บ &correlator ไม่เปลี่ยนแปลงตลอดอายุการใช้งานของหน้าเว็บหรือเซสชันของผู้ใช้ในแอป คุณยังคงควบคุมตัวเชื่อมโยงสตรีม &scor ได้ ซึ่งคุณต้องรีเซ็ต สำหรับสตรีมใหม่แต่ละรายการโดยการสร้าง Nonce ใหม่

    คำขอโฆษณาทั้งหมดของสตรีมเดียวกันต้องแชร์อินสแตนซ์ NonceLoader เดียวกัน และค่าสหสัมพันธ์ของสตรีมเพื่อให้ฟีเจอร์การกำหนดความถี่สูงสุดและการยกเว้นโฆษณาของคู่แข่ง ทำงานได้

  2. สร้าง Nonce

    public void generateNonceForAdRequest(View view) {
  logMessage("Generate Nonce Request");
  Set supportedApiFrameWorksSet = new HashSet();
  // The values 2, 7, and 9 correspond to player support for VPAID 2.0,
  // OMID 1.0, and SIMID 1.1.
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest =
      NonceRequest.builder()
          .descriptionURL("https://example.com/content1")
          .iconsSupported(true)
          .omidPartnerVersion("6.2.1")
          .omidPartnerName("Example Publisher")
          .playerType("ExamplePlayerType")
          .playerVersion("1.0.0")
          .ppid("testPpid")
          .sessionId("Sample SID")
          .supportedApiFrameworks(supportedApiFrameWorksSet)
          .videoPlayerHeight(480)
          .videoPlayerWidth(640)
          .willAdAutoPlay(true)
          .willAdPlayMuted(false)
          .build();

  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(
          new OnSuccessListener<NonceManager>() {
            @Override
            public void onSuccess(NonceManager manager) {
              nonceManager = manager;
              String nonceString = manager.getNonce();
              logMessage("Nonce generated");
              logMessage(nonceString.substring(0, 20) + "...");
              Log.i(LOG_TAG, "Generated nonce: " + nonceString);

              // From here you would trigger your ad request and move on to initialize content.
              exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);

              adClickButton.setEnabled(true);
            }
          })
      .addOnFailureListener(
          new OnFailureListener() {
            @Override
            public void onFailure(Exception error) {
              logMessage("Nonce generation failed");
              Log.e(LOG_TAG, "Nonce generation failed: " + error.getMessage());
            }
          });
}

    MainActivity.java

    คุณต้องใช้ Nonce เพียงรายการเดียวสำหรับคำขอโฆษณาทั้งหมดในการเล่นสตรีมเดียว สำหรับการทดสอบ ให้เรียกใช้ฟังก์ชันนี้เมื่อคลิกปุ่มในแอปทดสอบ ของคุณ พารามิเตอร์ NonceRequest ที่ตั้งค่าไว้ในคู่มือนี้เป็นพารามิเตอร์ตัวอย่าง ตั้งค่าพารามิเตอร์ตามลักษณะของแอปของคุณเอง

    ฟังก์ชันนี้จะสร้าง Nonce แบบไม่พร้อมกัน คุณต้องจัดการทั้งกรณีที่คำขอ Nonce สำเร็จและไม่สำเร็จ หลังจากที่ตัวจัดการ Nonce พร้อมใช้งานแล้ว ให้เรียกข้อมูล Nonce ก่อนที่จะ สร้างคำขอโฆษณาโดยใช้เมธอด nonceManager.getNonce()

แนบ Nonce ไปกับคำขอโฆษณา

หากต้องการใช้ Nonce ที่สร้างขึ้น ให้ต่อท้ายแท็กโฆษณาด้วยพารามิเตอร์ givn และค่า Nonce ก่อนที่จะส่งคำขอโฆษณา

// From here you would trigger your ad request and move on to initialize content.
exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
MainActivity.java

ติดตามเหตุการณ์การเล่น

หากต้องการติดตามเหตุการณ์การเล่น คุณต้องตั้งค่าตัวแฮนเดิลเหตุการณ์เพื่อส่งสัญญาณโฆษณาไปยัง Google โดยทำดังนี้

// Triggered when a user clicks-through on an ad which was requested using a PAL nonce.
public void sendAdClick(View view) {
  logMessage("Ad click sent");
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

// In a typical PAL app, this is called when a user touch or click is detected,
// on the ad other than an ad click-through.
public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendAdTouch(e);
  }
}

// In a typical PAL app, this is called when a content playback session starts.
public void sendPlaybackStart() {
  logMessage("Playback start");
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

// In a typical PAL app, this is called when a content playback session ends.
public void sendPlaybackEnd() {
  logMessage("Playback end");
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

MainActivity.java

คุณควรเรียกใช้แต่ละฟังก์ชันในการติดตั้งใช้งานเมื่อใด

  • sendPlaybackStart(): เมื่อเซสชันการเล่นวิดีโอเริ่มต้นขึ้น
  • sendPlaybackEnd(): เมื่อเซสชันการเล่นวิดีโอสิ้นสุดลง
  • sendAdClick(): ทุกครั้งที่ผู้ชมคลิกโฆษณา
  • sendTouch(): ทุกครั้งที่มีการโต้ตอบกับเพลเยอร์

แนบเมธอดตัวแฮนเดิลเหตุการณ์กับเหตุการณ์การคลิกปุ่มเพื่อวัตถุประสงค์ในการทดสอบ ในการติดตั้งใช้งานเวอร์ชันที่ใช้งานจริง ให้ตั้งค่าแอปสำหรับเหตุการณ์ของผู้เล่นเพื่อเรียกใช้ เมธอดตัวแฮนเดิลเหตุการณ์

(ไม่บังคับ) ส่งสัญญาณ Google Ad Manager ผ่านเซิร์ฟเวอร์โฆษณาบุคคลที่สาม

เมื่อตั้งค่าเซิร์ฟเวอร์โฆษณาของบุคคลที่สามให้ทำงานร่วมกับ Google Ad Manager โปรดดูเอกสารประกอบของเซิร์ฟเวอร์เพื่อบันทึกและส่งต่อค่า Nonce ในคำขอโฆษณาแต่ละรายการ ตัวอย่างที่ระบุคือ URL คำขอโฆษณาที่มีพารามิเตอร์ Nonce รวมอยู่ พารามิเตอร์ Nonce จะแพร่กระจายจาก PAL SDK ผ่านเซิร์ฟเวอร์ตัวกลาง แล้วไปยัง Ad Manager ซึ่งช่วยให้สร้างรายได้ได้ดียิ่งขึ้น

กำหนดค่าเซิร์ฟเวอร์โฆษณาบุคคลที่สามให้รวม Nonce ไว้ในคำขอของเซิร์ฟเวอร์ที่ส่งไปยัง Ad Manager ตัวอย่างแท็กโฆษณาที่กำหนดค่าภายในเซิร์ฟเวอร์โฆษณาบุคคลที่สามมีดังนี้

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

ดูรายละเอียดเพิ่มเติมได้ที่คู่มือการติดตั้งฝั่งเซิร์ฟเวอร์ของ Google Ad Manager

Ad Manager จะค้นหา givn= เพื่อระบุค่า Nonce เซิร์ฟเวอร์โฆษณาของบุคคลที่สามต้องรองรับมาโครบางอย่างของตัวเอง เช่น %%custom_key_for_google_nonce%% และแทนที่ด้วยพารามิเตอร์การค้นหา Nonce ที่คุณระบุในขั้นตอนก่อนหน้า ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการนี้ได้ในเอกสารประกอบของเซิร์ฟเวอร์โฆษณาของบุคคลที่สาม