مرجع API

طرق Adsgram

init

ينشئ AdController الذي يُستخدم لعرض وتحميل وإتلاف الإعلان.
يكفي التهيئة مرة واحدة فقط لكل blockId.
إذا استدعيت دالة init بنفس blockId أكثر من مرة، ستحصل على نفس AdController لهذا blockId.

الصيغة

const AdController = window.Adsgram.init({
  blockId: "your-block-id",
  debug: true,
  debugConsole: true,
  debugBannerType: "FullscreenMedia"
});

المعلمات

blockId

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

debug Optional

قيمة منطقية إذا تم تعيينها إلى true ستحصل على استجابة من الخادم بإعلان اختبار وسيتم إخراج سجلات مفصلة بالبادئة ADSGRAM DEBUG LOG إلى وحدة تحكم المتصفح لتصحيح أخطاء الدمج.

خطر

لا تنسَ الإزالة أو التعيين إلى false عند الإصدار للإنتاج.
لا نضيف مرات عرض الإعلان الاختباري إلى الإحصائيات، لذا لن ترى إحصائيات عروضها أو نقراتها إلخ على صفحة المنصة والكتلة.
لن يتم إرسال طلب إلى Reward Url.

debugConsole Optional

قيمة منطقية. الافتراضي هو true. يعمل فقط إذا كانت معلمة debug صحيحة.
إذا كانت true، سيتم إخراج السجلات التفصيلية بالبادئة ADSGRAM DEBUG LOG إلى وحدة تحكم المتصفح. إذا كانت false، لا يتم إخراج السجلات إلى وحدة التحكم، حتى في وضع التصحيح.

debugBannerType Optional

القيم الممكنة هي "FullscreenMedia" و "RewardedVideo".
استخدم هذه القيمة عندما تريد الحصول على نوع إعلان اختباري محدد. يعمل فقط إذا كانت معلمة debug تساوي true.

القيمة المُرجعة

AdController

طرق AdController

show

يُحمّل ويُظهر الإعلان.

الصيغة

javascript

AdController.show();

typescript

const showPromise: Promise<ShowPromiseResult> = AdController.show();

القيمة المُرجعة

Promise يتم حله إذا شاهد المستخدم الإعلان حتى النهاية، وإلا يتم رفضه.
نتيجة الوعد لها الأنواع التالية:

interface ShowPromiseResult {
  done: boolean; // صحيح إذا شاهد المستخدم حتى النهاية، خلاف ذلك خطأ
  description: string; // وصف الحدث
  state: 'load' | 'render' | 'playing' | 'destroy'; // حالة banner
  error: boolean; // صحيح إذا تم إصدار الحدث بسبب خطأ، خلاف ذلك خطأ
}

أمثلة

استخدام promises API:

javascript

AdController.show().then((result) => {
  // شاهد المستخدم الإعلان حتى النهاية
  // الكود الخاص بك لمكافأة المستخدم
}).catch((result) => {
  // حصل المستخدم على خطأ أثناء تشغيل الإعلان أو تخطى الإعلان
  // لا تفعل شيئاً أو افعل ما تريد
})

typescript

AdController.show().then((result: ShowPromiseResult) => {
  // شاهد المستخدم الإعلان حتى النهاية
  // الكود الخاص بك لمكافأة المستخدم
}).catch((result: ShowPromiseResult) => {
  // حصل المستخدم على خطأ أثناء تشغيل الإعلان أو تخطى الإعلان
  // لا تفعل شيئاً أو افعل ما تريد
})

يمكنك أيضاً تحقيق نفس السلوك باستخدام await

javascript

try {
  const showPromiseResult = await AdController.show();
  // شاهد المستخدم الإعلان حتى النهاية
  // الكود الخاص بك لمكافأة المستخدم
} catch (showPromiseResult) {
  // حصل المستخدم على خطأ أثناء تشغيل الإعلان أو تخطى الإعلان
  // لا تفعل شيئاً أو افعل ما تريد
}

typescript

try {
  const showPromiseResult: ShowPromiseResult = await AdController.show();
  // شاهد المستخدم الإعلان حتى النهاية
  // الكود الخاص بك لمكافأة المستخدم
} catch (showPromiseResult: ShowPromiseResult) {
  // حصل المستخدم على خطأ أثناء تشغيل الإعلان أو تخطى الإعلان
  // لا تفعل شيئاً أو افعل ما تريد
}

نصيحة

قم بربط الوعد بـ finally إذا كنت بحاجة إلى إضافة أي إجراء إضافي بعد انتهاء تشغيل الإعلان أو تخطيه أو حدوث خطأ.

destroy

لإيقاف عرض الإعلان وإزالة بيانات banner المحملة.

الصيغة

AdController.destroy();

القيمة المُرجعة

None(undefined)

معلومات

عادة لا تحتاج إلى استدعائها يدوياً، في حالة حدوث خطأ أو تخطي أو مشاهدة الإعلان بالكامل سيتم إتلافه تلقائياً.

addEventListener

يشترك في event ويستدعي دالة callback إذا تم تشغيل event.
يُستخدم إذا كنت تحتاج إلى مزيد من التحكم في عرض الإعلانات.

الصيغة

AdController.addEventListener('onReward', () => {
    // الكود الخاص بك لمكافأة المستخدم
});

المعلمات

event

أنواع الأحداث:

الحدث	يحدث
onStart	عندما يتم عرض أول إطار للـ banner
onSkip	عندما يغلق المستخدم الإعلان
onReward	عندما يشاهد المستخدم banner المكافأة حتى النهاية
onComplete	عندما يشاهد المستخدم banner interstitial حتى النهاية أو يغلقه
onError	عندما يحصل المستخدم على خطأ أثناء عرض أو تشغيل banner
onBannerNotFound	عندما لا يوجد banner للعرض
onNonStopShow	عندما يحاول المستخدم مشاهدة عدة إعلانات متتالية
onTooLongSession	عندما تكون الجلسة طويلة جداً، يحتاج المستخدم إلى إعادة تشغيل التطبيق للحصول على الإعلانات

نصيحة

إذا كنت تريد عرض تنبيه مخصص، يمكنك الاشتراك في onBannerNotFound أو onNonStopShow أو onTooLongSession.
وإلا سنعرض التنبيه الافتراضي.
يتم عرض التنبيه بلغة المستخدم أو بالإنجليزية
ويبدو هكذا 👇

callback

الدالة التي سيتم استدعاؤها عند حدوث حدث من النوع المحدد.

القيمة المُرجعة

None(undefined)

removeEventListener

يلغي الاشتراك في event مع callback المحدد

الصيغة

AdController.removeEventListener('onReward', rewardFunction);

المعلمات

نفس المعلمات في addEventListener

القيمة المُرجعة

None(undefined)