เริ่มต้น

ขั้นตอนแรกคือเพิ่ม Android PAL SDK ลงในแอป

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

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

app/build.gradle

...
dependencies {
    implementation 'com.google.android.gms:play-services-pal:22.0.0'
    ...
}

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

สร้าง Nonce

"Nonce" คือสตริงที่เข้ารหัสรายการเดียวที่ PAL สร้างขึ้นโดยใช้ NonceLoader PAL SDK กําหนดให้คําขอสตรีมใหม่แต่ละรายการต้องมาพร้อมกับ Nonce ที่สร้างขึ้นใหม่ อย่างไรก็ตาม คุณนํา Nonce มาใช้ซ้ำได้สําหรับคําขอโฆษณาหลายรายการภายในสตรีมเดียวกัน หากต้องการสร้าง Nonce โดยใช้ PAL SDK ให้ทําการเปลี่ยนแปลงใน MyActivity.java หากต้องการดูตัวอย่างแอปที่ใช้ PAL เพื่อสร้าง Nonce ให้ดาวน์โหลดตัวอย่างสำหรับ Android จาก GitHub

ก่อนอื่นคุณต้องนําเข้า PAL SDK, สร้างพร็อพเพอร์ตี้ส่วนตัวเพื่อจัดเก็บ NonceLoader และ NonceManager จากนั้นจึงเริ่มต้น NonceLoader

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

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

import android.app.Activity;
import android.os.Bundle;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

import java.util.HashSet;
import java.util.Set;

public class MainActivity extends Activity {
...
  private NonceLoader nonceLoader;
  private NonceManager nonceManager = null;
  private ConsentSettings consentSettings;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 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 isConsentToStorage = getConsentToStorage();

    videoView = findViewById(R.id.video_view);
    videoView.setOnTouchListener(this::onVideoViewTouch);

    consentSettings = ConsentSettings.builder()
            .allowStorage(isConsentToStorage)
            .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);
    ...
  }

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

ฟังก์ชันนี้จะทริกเกอร์การสร้าง Nonce แบบไม่เป็นเชิงเส้น คุณจึงต้องใช้ AsyncTask เพื่อจัดการกับคำขอ Nonce ที่สำเร็จหรือไม่สำเร็จ

public void generateNonceForAdRequest() {
  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();
  NonceCallbackImpl callback = new NonceCallbackImpl();
  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(callback)
      .addOnFailureListener(callback);
}

private class NonceCallbackImpl implements OnSuccessListener<NonceManager>, OnFailureListener {
  @Override
  public void onSuccess(NonceManager manager) {
    nonceManager = manager;
    String nonceString = manager.getNonce();
    Log.i("PALSample", "Generated nonce: " + nonceString);
    // from here you would trigger your ad request and move on to initialize content
  }

  @Override
  public void onFailure(Exception error) {
    Log.e("PALSample", "Nonce generation failed: " + error.getMessage());
  }
}

เมื่อสร้างเครื่องมือจัดการ Nonce แล้ว คุณจะเรียกข้อมูล Nonce ได้ทุกเมื่อโดยใช้ nonceManager.getNonce()

แนบ Nonce กับคําขอโฆษณา

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

/**
 * The ad tag for your ad request, for example:
 * https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external\
 * /single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1\
 * &cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
 *
 * For more sample ad tags, see
 * developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
 */
private static final String DEFAULT_AD_TAG = "Your ad tag";
...
@Override
public void onSuccess(NonceManager manager) {
  nonceManager = manager;
  String nonceString = manager.getNonce();
  Log.i("PALSample", "Generated nonce: " + nonceString);
  // Append the nonce to the ad tag URL.
  makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
}

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

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

public void sendAdClick() {
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

public void sendPlaybackStart() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

public void sendPlaybackEnd() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendTouch(e);
  }
}

ช่วงเวลาที่ควรเรียกใช้ฟังก์ชันแต่ละรายการในการนำไปใช้งานมีดังนี้

  • 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 ที่คุณระบุไว้ในขั้นตอนก่อนหน้า ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการนี้ได้ในเอกสารประกอบของเซิร์ฟเวอร์โฆษณาบุคคลที่สาม