ارجاع API

متدهای Adsgram

init

ایجاد AdController که برای نمایش، بارگذاری و حذف تبلیغ استفاده می‌شود.
برای هر blockId فقط یک بار مقداردهی اولیه کافی است.
اگر تابع init را با همان blockId بیش از یک بار فراخوانی کنید، همان AdController را برای آن blockId دریافت خواهید کرد.

Syntax

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 در کنسول مرورگر برای اشکال‌زدایی یکپارچه‌سازی نمایش داده می‌شوند.

خطر

فراموش نکنید که هنگام انتشار در production آن را حذف یا روی false تنظیم کنید.
ما نمایش‌های تبلیغ تست را به آمار اضافه نمی‌کنیم، بنابراین آمار نمایش‌ها، نمایش‌ها، کلیک‌ها و غیره آن را در صفحه پلتفرم و بلاک نخواهید دید.
درخواست به Reward Url ارسال نخواهد شد.

debugConsole Optional

مقدار بولین. پیش‌فرض true است. فقط در صورتی کار می‌کند که پارامتر debug روی true باشد.
اگر true باشد، لاگ‌های دقیق با پیشوند ADSGRAM DEBUG LOG در کنسول مرورگر نمایش داده می‌شوند. اگر false باشد، لاگ‌ها حتی در حالت debug نیز در کنسول نمایش داده نمی‌شوند.

debugBannerType Optional

مقادیر ممکن "FullscreenMedia" و "RewardedVideo" هستند.
از این مقدار زمانی استفاده کنید که می‌خواهید نوع بنر تست دقیق را دریافت کنید. فقط در صورتی کار می‌کند که پارامتر debug روی true باشد.

مقدار بازگشتی

AdController

متدهای AdController

show

بارگذاری و نمایش تبلیغ.

Syntax

javascript

AdController.show();

typescript

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

مقدار بازگشتی

Promise که اگر کاربر تبلیغ را تا انتها مشاهده کند resolve و در غیر این صورت rejected می‌شود.
نتیجه promise دارای انواع زیر است:

interface ShowPromiseResult {
  done: boolean; // true if user watch till the end, otherwise false
  description: string; // event description
  state: 'load' | 'render' | 'playing' | 'destroy'; // banner state
  error: boolean; // true if event was emitted due to error, otherwise false
}

مثال‌ها

استفاده از promises API:

javascript

AdController.show().then((result) => {
  // user watch ad till the end
  // your code to reward user
}).catch((result) => {
  // user get error during playing ad or skip ad
  // do nothing or whatever you want
})

typescript

AdController.show().then((result: ShowPromiseResult) => {
  // user watch ad till the end
  // your code to reward user
}).catch((result: ShowPromiseResult) => {
  // user get error during playing ad or skip ad
  // do nothing or whatever you want
})

همچنین می‌توانید همان رفتار را با استفاده از await به دست آورید

javascript

try {
  const showPromiseResult = await AdController.show();
  // user watch ad till the end
  // your code to reward user
} catch (showPromiseResult) {
  // user get error during playing ad or skip ad
  // do nothing or whatever you want
}

typescript

try {
  const showPromiseResult: ShowPromiseResult = await AdController.show();
  // user watch ad till the end
  // your code to reward user
} catch (showPromiseResult: ShowPromiseResult) {
  // user get error during playing ad or skip ad
  // do nothing or whatever you want
}

نکته

اگر نیاز دارید پس از پایان پخش تبلیغ، رد شدن آن یا بروز خطا، عمل اضافی اضافه کنید، promise را با finally زنجیر کنید.

destroy

برای توقف نمایش تبلیغ و حذف داده‌های بنر بارگذاری شده.

Syntax

AdController.destroy();

مقدار بازگشتی

None(undefined)

اطلاعات

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

addEventListener

عضویت در event و فراخوانی تابع callback در صورت رخ دادن event.
اگر نیاز به کنترل بیشتر روی نمایش تبلیغات دارید استفاده می‌شود.

Syntax

AdController.addEventListener('onReward', () => {
    // your code to reward user
});

پارامترها

event

انواع رویدادها:

رویداد	زمانی رخ می‌دهد
onStart	هنگام نمایش اولین فریم بنر
onSkip	هنگامی که کاربر تبلیغ را می‌بندد
onReward	هنگامی که کاربر بنر reward را تا انتها مشاهده می‌کند
onComplete	هنگامی که کاربر بنر interstitial را تا انتها مشاهده می‌کند یا آن را می‌بندد
onError	هنگامی که کاربر در حین نمایش یا پخش بنر با خطا مواجه می‌شود
onBannerNotFound	هنگامی که بنری برای نمایش وجود ندارد
onNonStopShow	هنگامی که کاربر سعی می‌کند چندین تبلیغ را پشت سر هم تماشا کند
onTooLongSession	هنگامی که جلسه خیلی طولانی است، کاربر باید اپلیکیشن را مجدداً راه‌اندازی کند تا تبلیغ دریافت کند

نکته

اگر می‌خواهید alert سفارشی خود را نمایش دهید، می‌توانید در onBannerNotFound، onNonStopShow یا onTooLongSession عضو شوید.
در غیر این صورت alert پیش‌فرض را نمایش خواهیم داد.
Alert به زبان کاربر یا انگلیسی نمایش داده می‌شود
و به شکل زیر است 👇

callback

تابعی که هنگام رخ دادن رویداد از نوع مشخص شده فراخوانی خواهد شد.

مقدار بازگشتی

None(undefined)

removeEventListener

لغو عضویت از event با callback مشخص شده

Syntax

AdController.removeEventListener('onReward', rewardFunction);

پارامترها

مشابه addEventListener

مقدار بازگشتی

None(undefined)