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

يستهدف هذا الدليل شبكات الإعلانات التي تسعى إلى إنشاء محوّل عروض أسعار. للمشاركة في عروض الأسعار في الوقت الفعلي (RTB) ضمن توسّط Google. إذا كنت ناشرًا، يمكنك الاطّلاع على مقالة توسّط الناشر على التعليمات

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

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

ملاحظة: تتطلّب المشاركة في عروض الأسعار أيضًا مقدّم عرض سعر يمكنه الاستجابة طلبات OpenRTB. الإرشادات حول كيفية متابعة مقدِّم عرض السعر خارج نطاق نطاق هذا الدليل

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

الإعداد

مسار مفصّل لمراحل نشاط عرض الطلب والاستجابة بالكامل لأحد المحوّلات كما هو موضح أدناه:

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

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

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

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

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

ملاحظة: تعمل حزمة "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. تتم إعادة توجيه معاودة الاتصال هذه إلى ناشري التطبيق حتى يتمكنوا من معرفة أنهم بدء تحميل الإعلانات

ملاحظة: يتم استدعاء الطريقة initialize() على مثيل مهمل لمحوِّل. ما مِن طرق أخرى سيتم استدعاءها في هذا المثيل تحديدًا. إذا كان المحوّل إلى حفظ الحالة بموجب هذه الطريقة، وبالتالي يجب أن تكون أي حالة ثابتة.

@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(). مع سلسلة توضح الخطأ الذي حدث.

ملاحظة: يمكن أن تمثل سلسلة الإشارات أي كائن، ويمكن أن تكون في أي كتنسيق JSON العادي أو بترميز Base64 أو أي شكل آخر من أشكال التشفير نختارها. يُنصَح بتشفير الإشارات لضمان تعتيم الإشارات. خارج شبكتك

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

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

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

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

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

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

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

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

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

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

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

لدى "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 لإعلانات الأجهزة الجوّالة إعادة توجيهها إلى الناشر.

ويجب أن تستدعي المحوّلات الأحداث التالية عند اللزوم:

شائعة لجميع الأشكال
الطريقة	وقت الاتصال
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
onAdFailedToShow()	Impression failure^1
لا شيء مما سبق لعدة ثوانٍ	Impression recorded

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

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

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, ...);
  }
}