شروع کنید

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 یک رشته رمزگذاری شده واحد است که PAL با استفاده از کلاس NonceLoader تولید می کند. PAL نیاز دارد که هر درخواست جریان با یک nonce منحصر به فرد همراه باشد. با این حال، می‌توانید از nonces برای چندین درخواست تبلیغات در یک جریان استفاده مجدد کنید. برای ایجاد یک 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 برای هر جلسه کاربر ایجاد کنید. اگر برنامه شما چندین صفحه یا ساختارهای معادل دارد، یک نمونه 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

    برای همه درخواست‌های تبلیغاتی در یک پخش جریانی تنها به یک نونس نیاز دارید. برای اهداف آزمایشی، هنگام کلیک کردن روی یک دکمه در برنامه آزمایشی خود، این تابع را فراخوانی کنید. پارامترهای NonceRequest که در این راهنما تنظیم شده اند، پارامترهای نمونه هستند. پارامترهای خود را بر اساس ویژگی های برنامه خود تنظیم کنید.

    این تابع یک 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 برای شناسایی مقدار nonce به دنبال givn= می گردد. سرور تبلیغات شخص ثالث باید از مقداری ماکرو خاص مانند %%custom_key_for_google_nonce%% پشتیبانی کند و آن را با پارامتر درخواست nonce که در مرحله قبل ارائه کردید جایگزین کند. اطلاعات بیشتر در مورد نحوه انجام این کار در مستندات سرور آگهی شخص ثالث موجود است.