شروع کنید

PAL به شما امکان می‌دهد سیگنال‌های تبلیغاتی گوگل را در درخواست‌های تبلیغاتی خود و در طول پخش تبلیغات ارسال کنید.

این راهنما شامل اضافه کردن Android PAL SDK به برنامه شما می‌شود. برای دیدن یک برنامه نمونه که از PAL برای تولید nonce استفاده می‌کند، نمونه اندروید را از GitHub دانلود کنید.

اضافه کردن Android PAL SDK به عنوان یک کتابخانه

از نسخه ۱۸.۰.۰، PAL SDK در مخزن Maven گوگل میزبانی می‌شود و می‌تواند به صورت زیر به برنامه شما اضافه شود:

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

از طرف دیگر، PAL SDK را می‌توان از مخزن Maven گوگل دانلود کرد و به صورت دستی به برنامه خود اضافه کرد.

تولید نانس

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

پیگیری رویدادهای پخش

برای ردیابی رویدادهای پخش، باید کنترل‌کننده‌های رویداد را طوری تنظیم کنید که سیگنال‌های تبلیغاتی را به گوگل ارسال کنند:

// 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() : هر بار که بیننده روی یک تبلیغ کلیک می‌کند
  • sendAdTouch() : در هر تعامل لمسی با بازیکن

برای اهداف آزمایشی، متدهای مدیریت رویداد را به رویدادهای کلیک دکمه متصل کنید. در پیاده‌سازی در محیط عملیاتی، برنامه خود را طوری تنظیم کنید که رویدادهای بازیکن، متدهای مدیریت رویداد را فراخوانی کنند.

(اختیاری) ارسال سیگنال‌های 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 مراجعه کنید.

مدیر تبلیغات برای شناسایی مقدار nonce به دنبال givn= می‌گردد. سرور تبلیغات شخص ثالث باید از برخی ماکروهای خاص خود، مانند %%custom_key_for_google_nonce%% ، پشتیبانی کند و آن را با پارامتر جستجوی nonce که در مرحله قبل ارائه دادید، جایگزین کند. اطلاعات بیشتر در مورد نحوه انجام این کار در مستندات سرور تبلیغات شخص ثالث موجود است.