تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

دمج AdColony مع التوسط

يوضِّح لك هذا الدليل كيفية استخدام "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" لتحميل إعلانات من AdColony وعرضها باستخدام التوسّط، مع تغطية كل من عمليات دمج عروض الأسعار والعرض الإعلاني بدون انقطاع. كما يتناول كيفية إضافة AdColony إلى إعدادات توسّط الوحدة الإعلانية، وكيفية دمج حزمة تطوير البرامج (SDK) في AdColony والمحوّل في Android تطبيق.

عمليات الدمج وأشكال الإعلانات المتوافقة

يوفّر Ad Manager محوّل التوسّط في AdColony الإمكانات التالية:

الدمج
عروض الأسعار
شلال
التنسيقات
بانر
إعلان بيني
تم منح المكافأة
مدمجة مع المحتوى

المتطلّبات

المستوى 19 أو أعلى لواجهة برمجة تطبيقات Android

[لتقديم عروض الأسعار]: محوّل AdColony بالإصدار 3.3.10.1 أو إصدار أحدث (يُنصح باستخدام أحدث إصدار)

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

الخطوة 1: ضبط الإعدادات في واجهة مستخدم AdColony

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

إعداد تطبيق جديد في AdColony

املأ النموذج وانقر على إنشاء في أسفل الصفحة لإضافة تطبيقك إلى AdColony.

إنشاء تطبيق AdColony

بعد إنشاء تطبيقك، يمكنك الحصول على رقم تعريف التطبيق من خلال الانتقال إلى تحقيق الربح > التطبيقات ضمن القسم معلومات التطبيق الأساسية لتطبيقك.

رقم تعريف تطبيق AdColony

بعد ذلك، يمكنك إنشاء منطقة إعلانية جديدة بالنقر على الزر إعداد منطقة إعلانية جديدة في قسم المناطق الإعلانية في صفحة تطبيقك. نقترح عليك إنشاء منطقة إعلانية جديدة للتوسّط مع Ad Manager حتى إذا سبق لك إنشاؤها.

منطقة إعداد AdColony

للحصول على تعليمات إضافية حول إنشاء موضع الإعلان، حدد علامة التبويب المناسبة لشكل الإعلان المفضّل لديك.

اضبط المنطقة نشطة؟ على نعم.
أدخِل اسمًا للمنطقة الإعلانية.
اختر إعلان البانر باعتباره حجم منطقة الإعلان.
يُرجى إدخال قيمة في حقل الحد الأقصى اليومي لمرات التشغيل.

إعلان بيني

اضبط المنطقة نشطة؟ على نعم.
أدخِل اسمًا للمنطقة الإعلانية.
اختر ما قبل التشغيل/إعلان بيني باعتباره نوع المنطقة.
يُرجى إدخال قيمة في حقل الحد الأقصى اليومي لمرات التشغيل.

تم منح المكافأة

اضبط المنطقة نشطة؟ على نعم.
أدخِل اسمًا للمنطقة الإعلانية.
اختَر تبادل القيمة/V4VC باعتباره نوع المنطقة.
اضبط من جهة العميل فقط؟ على نعم وأدخِل اسم العملة الافتراضية والحد الأقصى اليومي للفيديوهات لكل مستخدم ومبلغ المكافأة.

ملاحظة: يُعيد المحوِّل إعادة توجيه قيمة المكافأة المحددة هنا ما لم يتم إلغاء قيم المكافأة في Ad Managerواجهة المستخدم.
يُرجى إدخال قيمة في حقل الحد الأقصى اليومي لمرات التشغيل.

انقر على الزر إنشاء عند الانتهاء من إنشاء "المنطقة الإعلانية".

بعد إنشاء "المنطقة الإعلانية"، يمكنك العثور على رقم تعريف المنطقة ضمن قسم الدمج في "المنطقة الإعلانية". سيتم استخدام رقم تعريف المنطقة في الخطوة التالية.

رقم تعريف منطقة AdColony

تحديد موقع مفتاح واجهة برمجة تطبيقات AdColony

عروض الأسعار

هذه الخطوة غير مطلوبة لعمليات دمج عروض الأسعار.

شلال

ستحتاج إلى مفتاح واجهة برمجة تطبيقات AdColony لإعداد Ad Manager رقم تعريف الوحدة الإعلانية. انتقِل إلى إعدادات الحساب في لوحة بيانات الناشر في AdColony لتحديد موقع مفتاح واجهة برمجة التطبيقات.

إعدادات AdColony

تفعيل وضع الاختبار

لتفعيل الإعلانات الاختبارية على AdColony، انتقِل إلى لوحة بيانات AdColony وانتقِل إلى تحقيق الربح > التطبيقات. اختَر المنطقة التي تريد تفعيل الإعلانات الاختبارية لها ضمن قسم مناطق الإعلانات في تطبيقك. ويمكن تفعيل الإعلانات الاختبارية من خلال تحديد نعم إلى عرض الإعلانات الاختبارية فقط؟ ضمن قسم التطوير.

اختبار AdColony

الخطوة 2: إعداد طلب AdColony في Ad Manager واجهة المستخدم

سجِّل الدخول إلى حسابك على "مدير الإعلانات".

إضافة AdColony في الشركات

عروض الأسعار

هذه الخطوة غير مطلوبة لعمليات دمج عروض الأسعار.

شلال

انتقِل إلى المشرف > الشركات، ثم انقر على الزر شركة جديدة في علامة التبويب جميع الشركات. اختَر شبكة الإعلانات.

اختَر AdColony باعتبارها شبكة الإعلانات، وأدخِل اسمًا فريدًا وفعِّل التوسّط. فعِّل خيار الجمع التلقائي للبيانات، وأدخِل API Key الذي تم الحصول عليه في القسم السابق.

لست بحاجة إلى إدخال اسم مستخدم أو كلمة مرور. انقر على حفظ عند الانتهاء.

تفعيل ميزة مشاركة الإشارات الآمنة

عروض الأسعار

انتقِل إلى المشرف > الإعدادات العامة. انتقِل إلى علامة التبويب إعدادات حساب Ad Exchange وراجِع خيار مشاركة الإشارات الآمنة وفعِّله. النقر على حفظ

شلال

هذه الخطوة غير مطلوبة لعمليات دمج العرض الإعلاني بدون انقطاع.

ضبط AdColony عروض الأسعار

عروض الأسعار

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

اختَر AdColony كمقدِّم عروض الأسعار.

فعِّل الخيار إضافة مكتبة إشارات مقدِّم عرض السعر هذا إلى قائمة الإشارات المسموح بها والسماح بمشاركة الإشارات مع مقدِّم عرض السعر هذا. بعد ذلك، انقر على متابعة.

انقر على متابعة.

انقر على تم.

شلال

هذه الخطوة غير مطلوبة لعمليات دمج العرض الإعلاني بدون انقطاع.

إعداد ربط الوحدات الإعلانية

عروض الأسعار

انتقِل إلى العرض > مقدِّمو عروض الأسعار، واختَر الشركة AdColony ضمن علامة التبويب عروض الأسعار باستخدام حِزم تطوير البرامج (SDK).

انتقِل إلى علامة التبويب تعيين الوحدات الإعلانية وانقر على تعيين وحدة إعلانية جديدة.

اختَر وحدة إعلانية معيَّنة. اختر وحدة إعلانية شكلاً، وتطبيق للأجهزة الجوّالة كنوع المستودع، ثم تطبيق الأجهزة الجوّالة. بعد ذلك، أدخِل App ID and Zone ID الذي تم الحصول عليه في القسم السابق. وأخيرًا، انقر على حفظ.

شلال

انتقِل إلى عرض الإعلانات > مجموعات الأرباح وانقر على الزر مجموعة أرباح جديدة. اختر تطبيق الأجهزة الجوّالة.

انتقِل للأسفل وانقر على إضافة شريك أرباح.

حدد الشركة التي أنشأتها من أجلها AdColony في القسم السابق. اختَر توسّط حزمة تطوير البرامج (SDK) للأجهزة الجوّالة باعتباره نوع الدمج وAndroid كالنظام الأساسي ونشط كالحالة.

أدخِل القيمة App ID and Zone ID التي تم الحصول عليها في القسم السابق، وقيمة التكلفة التلقائية لكل ألف ظهور. انقر على حفظ.

ملاحظة: يستغرق جمع البيانات تلقائيًا بضعة أيام قبل أن يتمكّن من حساب قيمة التكلفة لكل ألف ظهور الديناميكية لشبكة التوسط بدقة. بعد احتساب التكلفة الفعلية لكل ألف ظهور، يتم تعديلها تلقائيًا نيابةً عنك.

إضافة AdColony إلى قائمة شركاء الإعلانات الذين يخضعون للّائحة العامة لحماية البيانات (GDPR) ولوائح الولايات الأمريكية

اتّبِع الخطوات الواردة في إعدادات اللائحة العامة لحماية البيانات و إعدادات اللوائح السارية في الولايات الأمريكية لإضافة AdColony إلى اللائحة العامة لحماية البيانات (GDPR) وقائمة شركاء الإعلانات للوائح الولايات الأمريكية في Ad Manager واجهة المستخدم.

الخطوة 3: استيراد حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony ومحوّلها

دمج "استوديو Android" (يُنصح به)

في ملف build.gradle.kts على مستوى التطبيق، أضِف تبعيات التنفيذ وعمليات الضبط التالية. استخدِم أحدث إصدار من حزمة تطوير البرامج (SDK) لـ AdColony ومحوّلها:

dependencies {
    implementation("com.google.android.gms:play-services-ads:23.0.0")
    implementation("com.google.ads.mediation:adcolony:4.8.0.2")
}

نقل المشروع إلى AndroidX

تعتمد حزمة AdColony SDK على مكتبات دعم Android، إلا أنّ أحدث إصدار من "SDK لإعلانات Google على الأجهزة الجوّالة" يستخدم مكتبات Jetpack.

للتأكّد من توافق حزمة AdColony SDK مع حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"، أنشئ ملف gradle.properties في المستوى الأعلى من مشروعك، وأضِف الرمز التالي:

android.useAndroidX=true
android.enableJetifier=true

سيؤدي هذا الإجراء إلى إعادة كتابة البرنامج الثنائي لحزمة AdColony SDK لاستخدام مكتبات Jetpack. يمكنك الاطّلاع على دليل نقل بيانات AndroidX للحصول على مزيد من المعلومات حول هذه الإعدادات.

الدمج اليدوي

نزِّل حزمة تطوير البرامج (SDK) لنظام التشغيل Android AdColony واستخرج adcolony.jar ضمن مجلد Library وأضِفها إلى مشروعك.
تعتمد حزمة تطوير البرامج (SDK) في AdColony على "مكتبة دعم التعليقات التوضيحية". راجع تحسين فحص الرمز باستخدام التعليقات التوضيحية للحصول على مزيد من التفاصيل حول كيفية إضافة مكتبة دعم التعليقات التوضيحية إلى مشروعك.
انتقِل إلى عناصر محوّل AdColony في مستودع Maven من Google. اختَر أحدث إصدار ونزِّل ملف .aar الخاص بمحوّل AdColony وأضِفه إلى مشروعك.

الخطوة 4: تنفيذ إعدادات الخصوصية في حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony

موافقة الاتحاد الأوروبي واللائحة العامة لحماية البيانات

بموجب سياسة موافقة المستخدم في الاتحاد الأوروبي التي تتّبعها Google، عليك التأكّد من الإفصاح عن معلومات محدّدة للمستخدمين في المنطقة الاقتصادية الأوروبية والحصول على موافقات منهم بشأن استخدام معرّفات الأجهزة والبيانات الشخصية. تعكس هذه السياسة متطلبات "التوجيه الأوروبي بشأن الخصوصية الإلكترونية" و"اللائحة العامة لحماية البيانات" (GDPR) في الاتّحاد الأوروبي. عند طلب الحصول على موافقة، يجب عليك تحديد كل شبكة إعلانات في سلسلة التوسط قد تجمع البيانات الشخصية أو تتلقاها أو تستخدمها، وتقدم معلومات عن استخدام كل شبكة. ولا يمكن لشركة Google حاليًا تمرير خيار موافقة المستخدم إلى هذه الشبكات تلقائيًا.

يوفّر محوّل AdColony الطريقة AdColonyMediationAdapter.getAppOptions() لتخصيص المَعلمات ليتم إرسالها إلى حزمة تطوير البرامج (SDK) الخاصة بـ AdColony. هناك طريقتان لهما صلة باللائحة العامة لحماية البيانات في هذين الخيارين، هما setPrivacyFrameworkRequired() وsetPrivacyConsentString(). يوضّح الرمز النموذجي التالي كيفية تمرير معلومات الموافقة إلى محوّل AdColony، الذي سيتم استخدامه بعد ذلك في طريقة الإعداد في AdColony. يجب ضبط هذه الخيارات قبل إعداد حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة لضمان إعادة توجيهها بشكل صحيح إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony.

Java

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter;
//...

AdColonyAppOptions appOptions = AdColonyMediationAdapter.getAppOptions();
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.GDPR, true);
appOptions.setPrivacyConsentString(AdColonyAppOptions.GDPR, "1");

Kotlin

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter
//...

val appOptions = AdColonyMediationAdapter.getAppOptions()
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.GDPR, true)
appOptions.setPrivacyConsentString(AdColonyAppOptions.GDPR, "1")

يمكنك الاطّلاع على تفاصيل تنفيذ "اللائحة العامة لحماية البيانات" في AdColony للحصول على مزيد من التفاصيل حول القيم التي يمكن تقديمها بهذه الطرق.

قوانين الخصوصية في الولايات الأمريكية

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

يوفّر محوّل AdColony الطريقة AdColonyMediationAdapter.getAppOptions() لتخصيص المَعلمات ليتم إرسالها إلى حزمة تطوير البرامج (SDK) الخاصة بـ AdColony. ثمة طريقتان لهما صلة بقانون خصوصية المستهلك في كاليفورنيا (CCPA) ضمن هذَين الخيارَين، هما setPrivacyFrameworkRequired() و setPrivacyConsentString(). يوضّح الرمز النموذجي التالي كيفية تمرير معلومات الموافقة إلى محوّل AdColony، الذي سيتم استخدامه بعد ذلك في طريقة الإعداد في AdColony. يجب ضبط هذه الخيارات قبل إعداد حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة لضمان إعادة توجيهها بشكل صحيح إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony.

Java

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter;
//...

AdColonyAppOptions appOptions = AdColonyMediationAdapter.getAppOptions();
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.CCPA, true);
appOptions.setPrivacyConsentString(AdColonyAppOptions.CCPA, "1");

Kotlin

import com.google.ads.mediation.adcolony.AdColonyMediationAdapter
//...

val appOptions = AdColonyMediationAdapter.getAppOptions()
appOptions.setPrivacyFrameworkRequired(AdColonyAppOptions.CCPA, true)
appOptions.setPrivacyConsentString(AdColonyAppOptions.CCPA, "1")

يمكنك الاطّلاع على تفاصيل تنفيذ قانون خصوصية المستهلك في كاليفورنيا (CCPA) لشركة AdColony للحصول على مزيد من التفاصيل حول القيم التي يمكن تقديمها من خلال هذه الطرق.

الخطوة 5: إضافة الرمز المطلوب

ما مِن رمز إضافي مطلوب لدمج AdColony.

الخطوة 6: اختبار عملية التنفيذ

تفعيل الإعلانات التجريبية

احرص على تسجيل جهاز الاختبار من أجل Ad Manager وتفعيل وضع الاختبار في واجهة المستخدم AdColony .

التحقّق من الإعلانات الاختبارية

للتأكّد من أنّك تتلقّى إعلانات اختبارية من AdColony، فعِّل اختبار مصدر إعلان فردي في "أداة فحص الإعلانات" باستخدام AdColony (Bidding) and AdColony (Waterfall) مصادر الإعلانات.

خطوات اختيارية

الأذونات

لتحقيق الأداء الأمثل، تنصح AdColony بإضافة الأذونات الاختيارية التالية إلى ملف AndroidManifest.xml الخاص بتطبيقك:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.VIBRATE" />

استخدام الإعلانات البينية والإعلانات التي تضم مكافأة

المعلمات الخاصة بالشبكة

يتيح محوّل AdColony استخدام معلَمات طلب إضافية يمكن تمريرها إلى المحوِّل باستخدام الفئة AdColonyBundleBuilder. يتضمّن AdColonyBundleBuilder الطرق التالية:

setShowPrePopup(boolean): لتحديد ما إذا كان سيتم عرض نافذة منبثقة قبل عرض الإعلان أم لا. يتم الضبط على "خطأ" لعدم ظهور أي نافذة منبثقة قبل عرض الإعلان.
setShowPostPopup(boolean): لتحديد ما إذا كان سيتم عرض نافذة منبثقة بعد عرض إعلان أم لا. ويتم الضبط على "خطأ" لعدم ظهور أي نوافذ منبثقة بعد عرض الإعلان.

في ما يلي مثال لرمز برمجي لكيفية ضبط مَعلمات طلبات الإعلان هذه:

Java

AdColonyBundleBuilder.setShowPrePopup(true);
AdColonyBundleBuilder.setShowPostPopup(true);

AdManagerAdRequest request = new AdManagerAdRequest.Builder()
  .addNetworkExtrasBundle(AdColonyAdapter.class, AdColonyBundleBuilder.build())
  .build();
rewardedInterstitialAd.loadAd(request);

Kotlin

AdColonyBundleBuilder.setShowPrePopup(true)
AdColonyBundleBuilder.setShowPostPopup(true)

val request = AdManagerAdRequest.Builder()
  .addNetworkExtrasBundle(AdColonyAdapter::class.java, AdColonyBundleBuilder.build())
  .build()
rewardedInterstitialAd.loadAd(request)

التحقّق من إصدارات المحوّل وحزمة تطوير البرامج (SDK)

لتسجيل إصدارات المحوّل وحزمة تطوير البرامج (SDK)، استخدِم مقتطف الرمز التالي:

AdColonyMediationAdapter adapter = new AdColonyMediationAdapter();
VersionInfo adapterVersion = adapter.getVersionInfo();
VersionInfo sdkVersion = adapter.getSDKVersionInfo();
// Log the adapter patch version to 3 digits to represent the x.x.x.x versioning
// used by adapters.
Log.d("TAG", String.format(
    "Adapter version: %d.%d.%03d",
    adapterVersion.getMajorVersion(),
    adapterVersion.getMinorVersion(),
    adapterVersion.getMicroVersion()));
Log.d("TAG", String.format(
    "SDK version: %d.%d.%d",
    sdkVersion.getMajorVersion(),
    sdkVersion.getMinorVersion(),
    sdkVersion.getMicroVersion()));

رموز الخطأ

إذا تعذّر على المحوّل تلقّي إعلان من AdColony، يمكن للناشرين التحقق من الخطأ الأساسي من استجابة الإعلان باستخدام ResponseInfo.getAdapterResponse() ضمن الفئات التالية:

com.jirbo.adcolony.AdColonyAdapter
com.google.ads.mediation.adcolony.AdColonyMediationAdapter

في ما يلي الرموز والرسائل المصاحبة التي يعرضها محوّل AdColony عند تعذُّر تحميل الإعلان:

رمز الخطأ	السبب
100	حدث خطأ في حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony.
101	معلَمات الخادم غير صالحة (مثلاً، رقم تعريف المنطقة غير متوفّر).
102	سبق أن تم طلب إعلان لرقم تعريف المنطقة نفسه.
103	حدث خطأ في الإعداد في حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony.
104	حجم البانر المطلوب غير مرتبط بحجم إعلان صالح في AdColony.
105	حدث خطأ في العرض التقديمي بسبب عدم تحميل الإعلان.
106	لم يكن السياق المستخدَم لإعداد حزمة AdColony SDK من أمثلة `Activity`.
من 0 إلى 3	حدث خطأ في حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony. يمكنك الاطّلاع على المستندات لمزيد من التفاصيل.
101	معلَمات الخادم غير صالحة (مثلاً، رقم تعريف المنطقة غير متوفّر).
102	وحدة التحكّم في العرض الجذر التي تعرض الإعلان هي `nil`.
103	حدث خطأ في الإعداد في حزمة تطوير البرامج (SDK) الخاصة بخدمة AdColony.
104	لا تتيح حزمة تطوير البرامج (SDK) في AdColony ضبط إعداداتها مرتين خلال فترة خمس ثوانٍ.
105	تعذّر عرض الإعلان.
106	إنّ المنطقة المستخدَمة لعرض المكافآت ليست منطقة مكافآت على بوابة AdColony.

سجلّ تغييرات مهايئ توسّط Android في AdColony