تطوير محوِّل عروض الأسعار

هذا الدليل مخصّص لشبكات المواقع الإعلانية التي تتطلّع إلى إنشاء محوِّل عروض أسعار من أجل المشاركة في عروض الأسعار في الوقت الفعلي ضمن توسّط Google. إذا كنت ناشرًا، يُرجى الاطّلاع على تعليمات توسّط الناشر.

محوِّل عروض الأسعار هو الجزء من جهة العميل في عملية الدمج. يسمح المحوِّل لحزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية بالاتصال بحزمة SDK لإعلانات Google على الأجهزة الجوّالة من أجل تحميل الإعلانات التي يعرضها مقدّم عرض السعر.

لكي يعمل عرض الأسعار بشكل صحيح، يجب أن يتولّى المحوِّل معالجة الإعداد وجمع الإشارات وتحميل الإعلانات وترحيل أحداث مراحل نشاط الإعلانات. سنرشدك في هذا الدليل إلى كيفية تنفيذ المحوّل للتعامل مع هذه العمليات.

سير عمل محوِّل عروض الأسعار

الإعداد

في ما يلي شرح تفصيلي لدورة حياة عرض الاستجابة للطلب-الاستجابة بالكامل للمحوِّل:

المحوِّل مسؤول عن الأجزاء التالية من سير العمل:

  • الخطوات من 4 إلى 7: تهيئة المحول ومعاودة الاتصال بحزمة SDK لإعلانات Google على الأجهزة الجوّالة بعد اكتمال التهيئة.

  • الخطوات من 10 إلى 13: جمع الإشارات من حزمة تطوير البرامج (SDK) لشبكة الإعلانات لإرسالها إلى نظام عروض الأسعار للمشاركة في طلب عرض الأسعار في الوقت الفعلي (RTB)، وإعادة توجيهها إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة".

  • الخطوات من 18 إلى 21: إذا أرجع نظام عرض السعر عرض السعر الفائز، عليك تحميل الإعلان وفقًا لردّ مقدِّم عرض السعر. بعد التحميل، أبلِغ حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" بأنّه قد تمّ تحميل الإعلان.

  • الخطوة 23 واللاحقة التالية: أثناء عرض إعلانك، يجب إعلام "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بأحداث مرات الظهور والنقرات، إضافةً إلى أحداث الإعلانات الأخرى التي تحدث خلال دورة حياة عرض الإعلان.

تنفيذ محوِّل عروض الأسعار

لإنشاء محوِّل عروض أسعار لحزمة "SDK لإعلانات Google على الأجهزة الجوّالة"، عليك زيادة فئة الخلاصة RtbAdapter. تشرح الأقسام التالية كل طريقة مجردة في RtbAdapter.

getSDKVersionInfo()

هنا يمكنك عرض إصدار حزمة SDK. ويتم تمرير هذه النسخة إلى نظام عروض الأسعار كجزء من طلب OpenRTB.

تتطلّب هذه الطريقة إرجاع VersionInfo. يوضّح المثال أدناه كيفية تحويل إصدار سلسلة حزمة SDK إلى تنسيق VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

يمكنك هنا إرجاع إصدار المحوِّل. ويتم تمرير هذه النسخة إلى نظام عروض الأسعار كجزء من طلب OpenRTB.

تستخدم المحوِّلات مفتوحة المصدر والمحوِّلات المستندة إلى إصدارات من Google مخطط إصدار للمهايئات مكون من 4 أرقام، لكن VersionInfo تسمح باستخدام 3 أرقام فقط. للتغلب على هذا الأمر، ننصح بدمج آخر رقمين في إصدار التصحيح، كما هو موضح أدناه.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

المهلة: 30 ثانية

إنّ طريقة initialize() هي أول طريقة يتم طلبها في المحوِّل. ويطلق عليها مرة واحدة فقط لكل جلسة. توفّر لك هذه الطريقة قائمة بكائنات MediationConfiguration التي تمثّل القائمة الكاملة لمواضع الإعلانات في هذا التطبيق التي تم ضبطها لشبكة المواقع الإعلانية. ويمكنك تكرار هذه القائمة لتحليل بيانات الاعتماد لكل موضع إعلان وتمرير البيانات ذات الصلة إلى حزمة تطوير البرامج (SDK) من أجل الإعداد.

بعد إعداد حزمة تطوير البرامج (SDK) وتصبح جاهزة لتلقّي طلبات الإعلانات، عليك استدعاء طريقة onInitializationSucceeded() من InitializationCompleteCallback. تتم إعادة توجيه معاودة الاتصال هذه إلى ناشري التطبيقات ليعرفوا أنّ بإمكانهم البدء في تحميل الإعلانات.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

المهلة: ثانية واحدة

في كل مرة يطلب فيها الناشر إعلانًا، يتم إنشاء مثيل جديد من RtbAdapter ويتم استدعاء طريقة collectSignals(). وسيتم استخدام هذه النسخة من العلامة RtbAdapter خلال مدة طلب الإعلان والاستجابة له ودورة نشاط عرضه لهذا الإعلان. تتيح طريقة collectSignals() لمعدِّلك تقديم إشارات من الجهاز يتم إرسالها إلى نظام عرض السعر في طلب OpenRTB.

تم استدعاء collectSignals() في سلسلة محادثات في الخلفية. تطلب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة في الوقت نفسه إشارات من جميع المحوِّلات المشاركة في عروض الأسعار. يُرجى احترام الغير وتقييد المكالمات بسلسلة محادثات واجهة المستخدم خلال هذه الفترة. أي عمل شاق يحتاجه المحوِّل أو حزمة تطوير البرامج (SDK) لجمع الإشارات يجب أن يتم تنفيذه من خلال طريقة initialize() وحفظها في ذاكرة التخزين المؤقت.

عندما تصبح إشاراتك جاهزة، يمكنك استدعاء دالة معاودة الاتصال onSuccess() باستخدام الإشارات المرمّزة.

إليك مثال على عملية التنفيذ:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

إذا تعذّر على المحوِّل جمع الإشارات، يمكنك الاتصال بـ signalCallbacks.onFailure() مع تقديم سلسلة توضّح الخطأ الذي حدث.

تطبيق طرق تحميل الإعلانات

المهلة: 10 ثوانٍ

وإذا أعاد نظام عرض السعر عرض السعر الفائز، تطلب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة المحوِّل لتحميل الإعلان الفائز، مع تمرير أي بيانات يعرضها نظام عرض السعر ويحتاجها حزمة تطوير البرامج لتحميل هذا الإعلان.

تعتمد طريقة التحميل الدقيقة التي يتم طلبها على شكل الإعلان المخصص لهذا الطلب:

شكل الإعلان طريقة التحميل
بانر loadBannerAd()
إعلان بيني loadInterstitialAd()
تم منح المكافأة loadRewardedAd()

نفِّذ هذه الطرق لأشكال الإعلانات المتوافقة مع المحوّل.

يتم استدعاء طريقة التحميل في سلسلة واجهة المستخدم، على نفس مثيل المحوِّل الذي قدمت منه الإشارات. وتوفِّر لك هذه الطريقة المَعلمات التالية:

  • سمة MediationAdConfiguration التي تحتوي على المَعلمات التي تحتاج إليها حزمة تطوير البرامج (SDK) لتحميل الإعلان لعرض السعر الفائز، مثل استجابة عرض السعر وأي بيانات اعتماد يضبطها الناشر في واجهة مستخدم AdMob.

  • يتم استخدام عنصر MediationAdLoadCallback لإشعار "SDK لإعلانات Google على الأجهزة الجوّالة" عند نجاح عملية التحميل أو تعذُّر إكمالها.

بعد تحميل حزمة تطوير البرامج (SDK) للإعلان، يمكنك استدعاء mediationAdLoadCallback.onSuccess(). عند تعذُّر تحميل الإعلان للحدث، يمكنك استدعاء الدالة mediationAdLoadCallback.onFailure() مع عرض سلسلة توضّح الخطأ الذي حدث.

تتطلّب الطريقة mediationAdLoadCallback.onSuccess() تمرير عنصر يؤكّد على إحدى واجهات "الإعلان" التي حدّدتها حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة. تطلب منك واجهات الإعلانات هذه تقديم بعض المعلومات عن الإعلان.

تحتوي MediationAdConfiguration أيضًا على الطريقة getWatermark() لعرض سلسلة بترميز base64 تمثل صورة PNG. يجب وضع هذه الصورة في تراكب شفاف على إعلاناتك. تواصَل مع Google للحصول على إرشادات إضافية حول كيفية عرض العلامة المائية. ويحتوي على بيانات وصفية حول الإعلان الذي يتم عرضه ليستخدمه الناشرون لتحديد مصدر الإعلانات المعروضة.

بالنسبة إلى إعلانات البانر، سيُطلب منك توفير طريقة عرض البانر. بالنسبة إلى الإعلانات البينية والإعلانات التي تضم مكافأة، سيُطلب منك تنفيذ طريقة show() لعرض الإعلان في وقت لاحق. ومن بين أفضل الممارسات، ننصحك بأن يكون صفك الذي يحمّل الإعلان مسؤولاً أيضًا عن تنفيذ طرق الإعلان هذه.

في ما يلي مثال على تنفيذ loadBannerAd(). تجدر الإشارة إلى أنّ طريقة تنفيذ المحوِّل ستبدو مختلفة، إذ يندمج المحوِّل مع حزمة تطوير برامج (SDK) مختلفة.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

أحداث مراحل نشاط عرض الإعلان في ترحيل البيانات

تتمثل المسؤولية النهائية للمحوِّل في إشعار حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بأي أحداث من مراحل نشاط العرض التقديمي، حتى يمكن إعادة توجيهها إلى الناشر. ويتوقّع الناشر معاودة الاتصال هذه في أوقات محدّدة بغضّ النظر عن شبكة الإعلانات التي تعرض الإعلان، لذا من المهم استدعاء أكبر عدد ممكن من طلبات معاودة الاتصال هذه في الوقت المناسب حتى تتمكّن "SDK لإعلانات Google على الأجهزة الجوّالة" من إعادة توجيهها إلى الناشر.

يجب أن يستدعي المحوِّلون الأحداث التالية عند الاقتضاء:

شائعة لجميع التنسيقات
الطريقة وقت الاتصال
reportAdClicked() تم النقر على الإعلان.
reportAdImpression() حقّق الإعلان مرّة ظهور.
onAdOpened() قدَّم الإعلان عرضًا بملء الشاشة.
onAdClosed() تم إغلاق عرض ملء الشاشة للإعلان.
onAdLeftApplication() تسبب الإعلان في مغادرة المستخدم للتطبيق.
الإعلانات التي تضم مكافآت
onRewarded() يتم منح المستخدم مكافأة.
معاودة الاتصال بالفيديو (الإعلانات بمكافأة والإعلانات المدمجة مع المحتوى)
onVideoStarted() بدأ فيديو الإعلان.
onVideoCompleted() اكتمل فيديو الإعلان.

يسترجع المحوِّل عنصر MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> عند طلب mediationAdLoadCallback.onSuccess(). من المتوقع أن تمسك المحوّلات بهذا العنصر واستخدامه لاستدعاء أحداث العرض التقديمي التي تحدث على إعلانك.

عادةً ما تعتمد معظم هذه الأحداث على حزمة تطوير البرامج (SDK) لشبكتك الإعلانية. ويتمثل دور المعدِّل ببساطة في تعيين عمليات الاستدعاء من حزمة SDK لشبكة الإعلانات إلى حزمة SDK لإعلانات Google على الأجهزة الجوّالة.

يوضح المثال التالي كيفية إعادة توجيه طلبات الاستدعاء من مستمع إعلانات حزمة SDK إلى حزمة SDK لإعلانات Google على الأجهزة الجوّالة:

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

مواد العرض المطلوبة لتتبُّع مرات ظهور الإعلانات المدمجة مع المحتوى

تسجِّل حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة مرة ظهور لإعلان مدمج مع المحتوى عند ظهور 1 بكسل من الإعلان. إذا كانت حزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية تتطلّب ظهور مواد عرض معيّنة من أجل تسجيل مرة ظهور صالحة، يمكن لنظام عرض الأسعار الإشارة إلى مواد العرض المدمجة المطلوبة هذه في استجابة عرض السعر. بعد ذلك، تتحقّق حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة من عرض مواد العرض المدمجة مع المحتوى المطلوبة قبل تسجيل مرّة ظهور.

راجِع مستندات مواد العرض المطلوبة المدمجة مع المحتوى لمزيد من المعلومات عن كيفية تحديد مواد العرض الإضافية المطلوبة في الاستجابة لعرض السعر.

عرض أخطاء الإعلانات

بالنسبة إلى أشكال الإعلانات بملء الشاشة، مثل الإعلانات البينية والإعلانات التي تضم مكافأة، ستوفّر عند تحميل معاودة الاتصال بنجاح، تنفيذ ما يلي: MediationInterstitialAd أو MediationRewardedAd بحيث تطلب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة من المحوّل عرض الإعلان.

تتوقع حزمة SDK لإعلانات Google على الأجهزة الجوّالة أنّه في حال نجح المحوِّل في تحميل إعلان، يكون الإعلان جاهزًا للعرض عندما يطلب الناشر عرضه. وهذا يعني أن كل استدعاء للعرض ينبغي أن يؤدي إلى مرة ظهور.

ومع ذلك، قد لا تتمكّن من عرض الإعلان في بعض الحالات. إذا لم تتمكن من عرض الإعلان، اتصِل على onAdFailedToShow() لإلغاء مرة الظهور.

يوضّح الجدول التالي مدى تأثير عمليات استدعاء العروض التقديمية في تسجيل مرات الظهور لأشكال الإعلانات بملء الشاشة:

هاتف معاودة الاتصال النتيجة
onAdOpened() Impression recorded
onAdErrorToShow() Impression failure1
لا شيء مما سبق لعدة ثوانٍ Impression recorded

1 بالنسبة إلى مرّات الظهور غير الناجحة، لا يتم تحصيل رسوم من شبكة المواقع الإعلانية مقابل مرّة الظهور، ولكن ذلك يؤثّر في تعديل معدّل الأحداث القابلة للفوترة. اطّلع على إشارات طلب عروض الأسعار لمزيد من المعلومات.

يوضح المثال الوهمي التالي دورة حياة التحميل/العرض حيث قد يؤدي طلب عرض إعلان إلى إخفاق.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}