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

ขั้นตอนแรกคือการเพิ่ม 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:20.2.0'
    ...
}

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

สร้าง Nonce

"ผลกระทบ" เป็นสตริงที่เข้ารหัสเพียงสตริงเดียวซึ่ง PAL สร้างขึ้นโดยใช้ NonceLoader PAL SDK กำหนดให้คำขอสตรีมใหม่แต่ละรายการต้องมีแท็ก 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 Manager แล้ว สามารถเรียกคืน 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 ที่คุณให้ไว้ในขั้นตอนก่อนหน้า ข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการนี้ มีอยู่ในเอกสารประกอบของเซิร์ฟเวอร์โฆษณาบุคคลที่สาม