پیاده سازی SDK در React Native

مرحله اول : اضافه کردن کتابخانه تپلیغ

در فولدر پروژه خود با استفاده از ابزارهای Command-Line دستور زیر را وارد نمایید:

 

npm install --save tapligh-react-native

سپس با استفاده از دستور زیر بسته تپلیغ را به پروژه خود متصل نمایید:

react-native link tapligh-react-native

اکنون می‌توانید از SDK این سرویس در برنامه خود استفاده نمایید.

توجه: این کتابخانه تنها قابلیت استفاده در Android را دارد.

نیازمندی های اولیه

  • حداقل نسخه اندروید مورد نیاز : 16
  • حداقل نسخه جاوای قابل پشتیبانی : 7

برای نمایش تبلیغات با استفاده از کتابخانه تپلیغ بایستی ابتدا ماژول Tapligh را در کد خود اضافه کنید سپس با فراخوانی متد مناسب نمایش تپلیغ، آن را در زمان مناسب به کاربر خود نشان دهید. در ادامه به صورت کامل درباره نحوه انجام این کار توضیح خواهیم داد.

ابتدا بایستی در صفحه ای که می­خواهید تپلیغ نمایش دهید، ماژول Tapligh را وارد کنید. برای این کار خط زیر را کپی کرده و در بالا کد خود قرار دهید:

import Tapligh from 'tapligh-react-native';

توجه داشته باشید که بایستی در اولین صفحه از برنامه خود حتما توکن برنامه خود را به کتابخانه تپلیغ معرفی نمایید. برای این منظور از خط زیر میتوانید استفاده کنید:

Tapligh.initialize();
Tapligh.setToken(YOUR-TOKEN, false);

در این کد عبارت YOUR-TOKEN توکنی است که شما پس از ثبت برنامه خود در پنل تپلیغ آن را دریافت میکنید.

در صورتیکه مقدار ورودی دوم این متد را true قرار دهید تبلیغات تست سیستم به شما نمایش داده میشود. این حالت برای زمانی مفید است که شما در حال آزمایش
هستید تا بهترین جای نمایش تپلیغ را برای برنامه خود پیدا کنید.
حال برای نمایش تبلیغ ابتدا بایستی تپلیغ را دریافت نمایید. به این منظور کد زیر را در جای مورد نظر کد خود قرار دهید:
var onAdReady = function(UNIT_CODE, AD_TOKEN) {
    // Handle showing ad when it's ready.
}

var onLoadError = function(UNIT_CODE, LOAD_ERROR) {
    // Handle error if the loadAd was not successful.
}

Tapligh.loadAd("UNIT-CODE", onAdReady, onLoadError);
برای استفاده از این متد سه ورودی لازم است. ورودی اول کد رشته مربوط به واحد تپلیغ است که در پنل برنامه خود ایجاد نموده اید.

با استفاده از ورودی دوم و سوم میتوانید نتیجه درخواست آماده سازی تپلیغ را دریافت کنید. در صورتیکه تبلیغ آماده باشد متد onAdReady صدا زده میشود. ورودی این متد توکن تبلیغی است که آماده نمایش است ورودی های این متد کد واحد تپلیغ درخواست شده و توکن تبلیغی است که آماده نمایش است،، در غیر اینصورت متد onLoadError صدا میشود.ورودی اول این متد کد واحد تپلیغی است که درخواست آماده سازی بر روی آن اجرا شده و ورودی دوم از نوع کلاس LoadErrorStatus بوده و مقادیری که میتوانند دریافت کنند به صورت زیر هستند:

  • noInternetAccess: در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده میشود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده میشود.
  • appNotFound: در صورتیکه توکن ارسالی به سرور اشتباه باشد و یا نام بسته تعریف شده در سرور با نام بسته برنامه متفاوت باشد، این پیغام برگردانده میشود.
  • noAdReady : در صورتیکه در این زمان و با شرایط برنامه شما تپلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده میشود.
  • adunitDisabled: در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تپلیغ متوقف شده و این پیغام در موبایل دریافت میشود.
  • adUnitNotFound: در صورتیکه رشته کدی که به عنوان واحد تپلیغ به ورودی این متد داده میشود دچار مشکل باشد و در سمت سرور تعریف نشده باشد این پیغام دریافت میشود. در این حالت رشته کد ورودی واحد تپلیغ رو چک کرده و در صورت وجود تفاوت آن را اصلاح نمایید.
  • adUnitNotReady: این مقدار در واحدهای بینابینی و در لحظه ای که ازنظر زمانی یا تعداد (بر اساس نوع تعریف واحد تپلیغ) موعد نمایش تبلیغ فرا نرسیده باشد برگردانده می شود.
  • internalError: این خطا در صورتی برگردانده میشود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره 42570000-021 داخلی 444 تماس حاصل نمایید.

    پس از آنکه متد onAdReady اجرا شد، به این معنی است که تبلیغ آماده نمایش است. بنابراین برای نمایش تبلیغ از متد زیر استفاده نمایید: 

var onAdResult = function(AD_RESULT, AD_TOKEN) {
    // Handle function for Ad result callback;
}

var onRewardReady = function(REWARD) {
    // Handle function for Ads with type of rewarded with amount of reward specified in application panel
}

Tapligh.showAd("UNIT-CODE", onAdResult, onRewardReady);
برای استفاده از این متد سه ورودی لازم است. ورودی اول رشته کد مربوط به واحد تپلیغی
است که در ورودی متد loadAd استفاده کردید.با استفاده از ورودی دوم و سوم میتوانید نتیجه نمایش تبلیغ را مشاهده کنید. در ادامه درباره این ورودی توضیحات بیشتری ارائه خواهیم داد.

دریافت نتیجه نمایش تبلیغ:

با استفاده از این ورودی که در هنگام نمایش تبلیغ تعیین می­کنید، می­توانید نتیجه درخواست نمایش آن را دریافت کنید. در صورتی که نمایش به صورت کامل انجام شده باشد، می­توانید میزان جایزه تعیین شده را نیز دریافت کنید.

این interface دو تابع به نام­های onAdResult و onRewardReady دارد. در تابع onAdResult دو مقدار قرار می­گیرد که مقدار اول نتیجه نمایش تپلیغ بوده و مقدار دوم توکنی است که برای این تپلیغ تعیین شده است. این توکن برای هر فرایند نمایش تپلیغ به صورت منحصر به فرد تعیین شده و می­توانید از طریق تابع دیگری از صحت این توکن اطمینان حاصل کنید. توضیحات کاملتر مربوط به توکن در ادامه داده خواهد شد.

var onAdResult = function(adResult, token) {
   console.log("Tapligh" , "token->" + token);
   switch (adResult){
     case "tokenExpired"": console.log("Tapligh", "tokenExpired"); break;
     case "adVideoClosedOnView": console.log("Tapligh", "adVideoClosedOnView"); break;
     case "adViewCompletely": console.log("Tapligh", "adViewCompletely"); break;
     case "adClicked": console.log("Tapligh", "adClicked"); break;
     case "adVideoClosedAfterFulView": console.log("Tapligh"  , "adVideoClosedAfterFulView"); break;
     case "skipAndClicked": console.log("Tapligh", "skipAndClicked"); break;
     case "skipAndClosed": console.log("Tapligh", "skipAndClosed"); break;
     // used for image ad
     case "adImageClosed": console.log("Tapligh", "adImageClosed");break;
   }
}

var onRewardReady = function(reward) {
   console.log("Tapligh" , "reward->" + reward);
}

مقادیر مربوط به نتیجه تپلیغ به صورت زیر هستند:

  • tokenExpired:در صورتی که این مقدار را دریافت کنید به این معنی است که تبلیغ لود شده، منقضی شده است. در این حالت از طریق متد loadAd دوباره باید درخواست تبلیغ بدهید.
  • adClicked : در صورتیکه کاربر بر روی تپلیغ کلیک کند این مقدار برگردانده می­شود. در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می­توانید واکنش­های مناسب خود را اجرا کنید.
  • adImageClosed : اگر کاربر بر روی علامت بستن تپلیغ تصویری نمایش داده شده کلیک کند این مقدار برگردانده می­شود. توجه کنید که این حالت شامل کلیک بر روی آیکون بستن تصویر انتهایی تپلیغ ویدیویی نمی­باشد و آن عملیات از طریق دو مقدار بعدی برگردانده می­شود. همچنین در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می­توانید واکنش­های مناسب خود را اجرا کنید.
  • adVideoClosedAfterFulView : در صورتیکه کاربر پس از نمایش کامل ویدیو بر روی علامت بستن تصویر انتهایی تپلیغ کلیک کند این مقدار برگردانده می­شود. در صورتیکه شما به کاربر به واسطه نمایش کامل ویدیو قصد دادن امتیاز، سکه و… را دارید از طریق این مقدار می­توانید این کار را انجام دهید.
  • adVideoClosedOnView : اگر کاربر حین نمایش تپلیغ ویدیویی آن را ببندد، این مقدار برگردانده می­شود. توجه کنید که در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می­توانید واکنش­های مناسب خود را اجرا کنید.
  • skipAndClicked: در صورتی که کاربر ویدیو را اسکیپ کرده و بر روی بنر نهایی ویدیو کلیک نماید این مقدار برگردانده می شود. فعالسازی قابلیت اسکیپ بر روی ویدیو از طریق تنظیمات واحد تپلیغ قابل ا اعمال است.
  • SkipAndClosed: در صورتی که کاربر ویدیو را اسکیپ کرده و در بنر انتهایی بر روی دکمه بستن آن کلیک نماید این مقدار برگردانده می شود. فعالسازی قابلیت اسکیپ بر روی ویدیو از طریق تنظیمات واحد تپلیغ قابل ا اعمال است.

نکته مهم: در صورتیکه پیش از اجرای متد loadAd متد showAd را فراخوانی کنید حتما در متد onAdResult با پاسخ noAdReady مواجه خواهید شد.

تمامی این مقادیر در کلاس AdResult قرار داده شده­اند و شما می­توانید آنها را مشاهده کنید.

 

لطفا نظرات خود را در زمینه تجربه استفاده از SDK از طریق developers@tapligh.com ، شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۴۴۴ و یا تلگرام با ما در میان بگذارید.

بررسی صحت اطلاعات نمایش تپلیغ:

برای توسعه دهندگانی که در ازای نمایش تبلیغات به کاربران جایزه می دهند، مطمئن شدن از درستی ااعتبار اطلاعاتی که در خصوص نمایش کامل تبلیغ دریافت میکنند از اهمیت بالایی برخوردار است. چراکه برخی کاربران با شبیهسازی این اطلاعات در صدد دریافت جایزه‌های بینهایت بر می آیند. سرویس تپلیغ با شناخت این دغدغه راه حل زیر را در اختیار توسعه دهندگان گذاشته است.
برای فرایند نمایش هر تبلیغ یک توکن منحصر به فرد ثبت می شود و توسعه دهنده می تواند این توکن را پس از پایان نمایش ودر هنگام دریافت نتیجه تبلیغ در تابع onRewardReady دریافت کند. سپس می تواند با استفاده از متد زیر وضعیت این توکن را در سرور تپلیغ بررسی نماید.
var onTokenVerified = function(TOKEN_RESULT) {
    if(TOKEN_RESULT == "SUCCESS") {
    //TODO write your code
    
    } else if (TOKEN_RESULT == "TOKEN_EXPIRED") {
    //TODO write your code
    
    } else if(TOKEN_RESULT == "NOT_USED") {
    //TODO write your code
    
    } else if(TOKEN_RESULT == "TOKEN_NOT_FOUND") {
    //TODO write your code
    
    } else if(TOKEN_RESULT == "INTERNAL_ERROR") {
    //TODO write your code
    
    }
}

Tapligh.verifyToken(“TOKEN”, onTokenVerified);

۵ حالت برای توکن می­تواند رخ داده باشد. شما می­توانید تمامی این مقادیر در کلاس TokenResult مشاهده نمایید:

  • Success: این مقدار به معنای موفقیت آمیز بودن نمایش تپلیغ بوده است. در این حالت کاربر ویدیو را به صورت کامل دیده است.
  • NOT_USED : اطلاعات مربوط به نمایش تپلیغ هنوز توسط سرور دریافت نشده است.
  • TOKEN_EXPIRED: توکن مربوطه منقضی شده است.
  • TOKEN_NOT_FOUND: توکن مربوطه در سرور وجود ندارد.
  • INTERNAL_ERROR: در صورت قطع بودن اتصال به اینترنت و یا بروز هرگونه خطا در ارتباط کتابخانه با سرور این مقدار برگردانده خواهد شد.

لطفا نظرات خود را در زمینه تجربه استفاده از SDK از طریق developers@tapligh.com ، شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۴۴۴ و یا تلگرام با ما در میان بگذارید.

جهت تست پروژه خود ترجیحا از Emulator ها استفاده ننمایید.

پروژه نمونه
دانلود پروژه نمونه