پیاده سازی SDK در Adobe Air

نحوه شروع کار با کتابخانه Adobe air

برای شروع به کار استفاده از کتابخانه تپلیغ در ابتدا باید یک حساب کاربری در تپلیغ ایجاد کنید (راهنمای ثبت نام) . پس از ثبت نام جهت ثبت اپلیکیشن خود جهت فعال سازی کتابخانه از بخش راهنمای اضافه کردن برنامه نسبت به ثبت برنامه های خود اقدام کنید و سپس کد فعال سازی کتابخانه را برای آن دریافت نمایید. در این مرحله کتابخانه adobe air را از اینجا دانلود کنید و سپس مراحل زیر را طی کنید :
۱ – با افزودن ANE تپلیغ به Flash/Fle، کار را شروع کنید.
  • در صورتیکه از Flash Builder استفاده می کنید، به پنجره پروپرتیز پروژه رفته، پس بیلد اسکریپت اکشن را از پنل سمت چپ انتخاب نموده تب Native Extensions را کلیک کنید. با انتخاب دکمه Add ANE تپلیغ را به build path. پروژ ه تان اضافه نمایید.
  • اگر از فلش Flash CC یا Animate CC استفاده می کنید، به File > Publish Settings رفته ایکون wrench را که در نزدیکی Script for ActionScript Settings است را کلیک نموده، سپس به مسیر لایبرری رفته، با جستجو دکمه Native Extension (ANE) فایل ANE تبلیغ را انتخاب کنید.

۲ – فایل application descriptor xml خود را باز کرده و در <android> tag’s <manifestAdditions> مجوزهای زیر را دنبال نمایید:

<span class="org-code"><uses-permission</span> <span class="prp-code">android</span>:name=<span class="grn-code">"android.permission.INTERNET"</span><span class="org-code">/></span>
<span class="org-code"><uses-permission</span> <span class="prp-code">android</span>:name=<span class="grn-code">"android.permission.ACCESS_NETWORK_STATE"</span><span class="org-code">/></span>
<span class="org-code"><uses-permission</span> <span class="prp-code">android</span>:name=<span class="grn-code">"android.permission.ACCESS_COARSE_LOCATION"</span><span class="org-code">/></span>

۳ – دقیقا بعد از تگ اپلیکیشن کدهای زیر را اضافه نماییدو در صورتیکه تگ اپلیکیشن را در آنجا مشاهده نمی کنید، یک تگ اپلیکیشن خالی را وارد نموده، و کد زیر را به عنوان یک زیر مجموعه بدان اضافه نمایید.

<span class="blu-code"><</span><span class="red-code">activity</span>
      <span class="red-code">android:name=</span>"<span class="blu-code">com.tapligh.sdk.ADView.ADView</span>"
      <span class="red-code">android:configChanges=</span>"<span class="blu-code">orientation|screenSize|screenLayout|keyboardHidden|uiMode</span>"
      <span class="red-code">android:theme</span>="<span class="blu-code">@android:style/Theme.Translucent.NoTitleBar</span>"<span class="blu-code">/></span>

<span class="blu-code"><</span><span class="red-code">receiver</span> <span class="red-code">android</span>:name="<span class="blu-code">com.tapligh.sdk.ADView.ADsReceiver</span>"<span class="blu-code">></span>
    <span class="blu-code"><</span><span class="red-code">intent-filter</span> android:priority="<span class="blu-code">999</span>"<span class="blu-code">></span>
        <span class="blu-code"><</span><span class="red-code">action</span> <span class="red-code">android:name</span>="<span class="blu-code">android.intent.action.PACKAGE_INSTALL</span>"<span class="blu-code">/></span>
        <span class="blu-code"><</span><span class="red-code">action</span> <span class="red-code">android:name</span>="<span class="blu-code">android.intent.action.PACKAGE_ADDED</span>"<span class="blu-code">/></span>
        <span class="blu-code"><</span><span class="red-code">action</span> <span class="red-code">android:name</span>="<span class="blu-code">android.intent.action.PACKAGE_REMOVED</span>"<span class="blu-code">/></span>
        <span class="blu-code"><</span><span class="red-code">data</span> <span class="red-code">android:scheme</span>="<span class="blu-code">package</span>"<span class="blu-code">/></span>
    <span class="blu-code"></</span><span class="red-code">intent-filter</span><span class="blu-code">></span>
<span class="blu-code"></</span><span class="red-code">receiver</span><span class="blu-code">></span>

شروع به کار با کتابخانه

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

در ابتدا باید یک ابجکت را از کلاس تپلیغ ANE پیدا نموده، و سپس تابع init را صدا بزنید.

var tapligh:TaplighAne = new TaplighAne();
tapligh.init();

سپس به وسیله زیر توکن اپلیکیشن خود را صدا زنید.

tapligh.setToken("YOUR-TOKEN");

Your-Token، توکنی است که شما در صورت وارد کردن اپلیکیشن حود در پنل تپلیغ، دریافت می نمایید.

قبل از نمایش هر تبلیغ، شما نیاز به load آن دارید. از متد load به صورت زیر استفاده کنید.

tapligh.loadAd("UNIT-CODE");

ورودی این تابع (UNIT-CODE) رشته  کد مربوط به واحد تپلیغی است که در پنل برنامه خود ایجاد کرده اید. جهت اطلاعات بیشتر درباره واحد تپلیغ به این قسمت مراجعه کنید.

تابع load تبلیغات با دادن یک پیغام،اپلیکشن شما را از نتیجه آگاه می کند. برای استفاده از آن شما نیاز به اضافه کردن یک listener پیام درکلاس TaplighAne که قبلا ایجاد کرده اید، دارید. در حالت تابع load تبلیغات ، امکان دریافت دو نوع پیام وجود دارد.

ON_AD_READY_EVENT and ON_LOAD_ERROR_EVENT

کد زیر را برای تنظیم listener این دو نوع پیام بکار برید.

tapligh.addEventListener(TaplighAne.ON_LOAD_ERROR_EVENT,onLoadError);
tapligh.addEventListener(TaplighAne.ON_AD_RESULT_EVENT,onAdResult);

فانکشنهای عملگر پیام شبیه موارد زیر می باشندو مقادیری که می توانند دریافت کنند به صورت زیر هستند:

private function onAdReady(e:AdReadyEvent):void
{
    trace("ad ready");
}
private function onLoadError(e:LoadErrorEvent):void
{
    trace("load error");
    trace(e.error);
}

The ON_AD_READY_EVENT

این بدان معنی است که واحد تپلیغ درخواستی شما در دسترس بوده، و شما می توانید جریان طبیعی نمایش تبلیغ را ادامه دهید

ON_LOAD_ERROR_EVENT

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

    • LoadErrorEvent.ERROR_NO_INTERNET_ACCESS : در صورت عدم ارتباط کاربر با اینترنت، این پیام دریافت خواهد شد. همچنین در حالتی که وای فای و یا دیتا روشن بوده، ولی ارتباط بر قرار نباشد، این پیام دریافت خواهد شد.
    • LoadErrorEvent.ERROR_BAD_TOKEN_USED : در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.
    • LoadErrorEvent.ERROR_NO_AD_READY : در صورتیکه توکن ارسالی به سرور اشتباه باشد و یا نام بسته تعریف شده در سرور با نام بسته برنامه متفاوت باشد، این پیغام برگردانده می شود.
    • LoadErrorEvent.ERROR_AD_UNIT_DISABLED : در صورتیکه در این زمان و با شرایط برنامه شما تپلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده می شود.
    • LoadErrorEvent.ERROR_AD_UNIT_NOT_FOUND : در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تپلیغ متوقف شده و این پیغام در موبایل دریافت می شود.
    • LoadErrorEvent.ERROR_INTERNAL_ERROR : در صورتیکه رشته کدی که به عنوان واحد تپلیغ به ورودی این متد داده می-شود دچار مشکل باشد و در سمت سرور تعریف نشده باشد این پیغام دریافت می شود. در این حالت رشته کد ورودی واحد تپلیغ رو چک کرده و در صورت وجود تفاوت آن را اصلاح نمایید.

ورودی UNIT-CODE همان واحد تپلیغ استفاده شده در load تبلیغ می باشد .

دریافت نتایج تبلیغ

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

برای دریافت نتایج تبلیغ، شما نیاز به بررسی ON_AD_RESULT_EVENT و ON_REWARD_READY_EVENT

tapligh.addEventListener(TaplighAne.ON_AD_RESULT_EVENT,onAdResult);
tapligh.addEventListener(TaplighAne.ON_REWARD_READY_EVENT,onRewardReady);

تابع listener شبیه این مورد میباشد :

private function onAdResult(e:AdResultEvent):void
{
	trace(e.result);
	if(e.result == AdResultEvent.RESULT_AD_VIEW_COMPLETELY)
	{
		trace("done");
	}
}
private function onRewardReady(e:RewardReadyEvent):void
{
	trace(e.reward);
}

نتیجه و توکن دو فیلد مربوط به کلاس AdResultEvent می باشند.توکن، مشاهده نتایج توکن می باشد، که با روش verifyToken قابل تایید است تا از مشاهده تبلیغ اطمینان حاصل گردد. فیلد نتایج می تواند یکی از این معیارهایی که تماما در فیلد استاتیک AdResultEvent تعریف شده اند را، برای راحتی استفاده، داشته باشند.

    • AdResultEvent.ERROR_NO_INTERNET_ACCESS : در صورت عدم ارتباط یوزر با اینترنت، این پیام دریافت خواهد شد. همچنین در حالتی که وای فای و یا دیتا روشن بوده، ولی ارتباط بر قرار نباشد، این پیام دریافت خواهد شد.
    • AdResultEvent.RESULT_BAD_TOKEN_USED : در صورتیکه توکن ارسالی نامعتبر بوده، و یا اسم پکیج شما با نام پکیج تعریف شده در پنل متفاوت باشد، این پیام دریافت خواهد شد.
    • AdResultEvent.RESULT_AD_VIEW_COMPLETELY : در صورتیکه کاربر بطور کامل ویدیوی تبلیغاتی را مشاهده کرده باشد این پیام داده خواهد شد.
    • AdResultEvent.RESULT_AD_CLICKED : در صورتیکه کاربر بر روی تبلیغ کلیک کند، این پیام داده خواهد شد. در اینجا فعالیت تپلیغ متوقف شده، و شما می توانید اقدامات مناسب را انجام دهید.
    • AdResultEvent.RESULT_AD_IMAGE_CLOSED : در صورتیکه کاربر کلید علامت ضربدر تبلیغ را در تصویر تپلیغ بزند، این پیام داده خواهد شد. توجه داشته باشید، که این حالت شامل بستن ویدیو بعد از مشاهده کامل آن نمی شود. همچنین شما می توانید اقدامات مناسب را در اینجا انجام دهید.
    • AdResultEvent.RESULT_AD_VIDEO_CLOSED_AFTER_FUL_VIEW : اگر کاربر پس از مشاهده کامل ویدیو، آنرا ببندد و اگر شما مایل به دادن سکه و یا امتیاز به کاربر پس از مشاهده تبلیغ می باشید، در اینجا می توانید اقدام نمایید.
    • AdResultEvent.RESULT_AD_VIDEO_CLOSED_ON_VIEW : در صورتیکه کاربر در حین مشاهده ویدیو، آنرا ببندد، این پیام داده خواهد شد. توجه داشته باشید، چون در این حالت فعالیت تپلیغ متوقف خواهد شد، شما می توانید اقدامات مناسب را در اینجا انجام دهید.
    • AdResultEvent.RESULT_INTERNAL_ERROR : این ارور زمانی رخ میدهد که مشکلی در ارتباط بین اس دی کی و سرور رخ دهد.
    • AdResultEvent.RESULT_NO_AD_READY : اگر شما قبل ازلود تبلیغ اقدام به نمایش تبلیغ کنید این ارور را دریافت می کنید.

ON_REWARD_READY_EVENT

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

بررسی صحت اطلاعات تبلیغ نمایش داده شده

برای توسعه دهندگانی که در ازای نمایش تبلیغات به کاربران جایزه می دهند، مطمئن شدن از درستی اعتبار اطلاعاتی که در خصوص نمایش کامل تبلیغ دریافت می کنند از اهمیت بالایی برخوردار است. چراکه برخی کاربران با شبیه سازی این اطلاعات در صدد دریافت جایزه های بینهایت بر می آیند. سرویس تپلیغ با شناخت این دغدغه راه حل زیر را در اختیار توسعه دهندگان گذاشته است.

برای فرایند نمایش هر تبلیغ یک توکن منحصر به فرد ثبت می شود و توسعه دهنده می تواند این توکن را پس از پایان فرایند نمایش ودر هنگام دریافت نتیجه تبلیغ از فیلد AdResultEvent.token دریافت کرده و در داخل ایونت onRewardReady صحت این توکن را از طریق متد زیر دریافت نماید:

tapligh.verifyToken(e.token);

خروجی این تابع یک ایونت به نام ON_TOKEN_VERIFIED_EVENT را فراخوانی می¬کند و بایستی به صورت زیر تعریف شود:

tapligh.addEventListener(TaplighAne.ON_TOKEN_VERIFIED_EVENT,onTokenVerified);

تابع نتیجه به صورت زیر خواهد بود:

private function onTokenVerified(e:TokenVerifiedEvent):void
{
	trace(e.result);
if(e.result == TokenVerifiedEvent.RESULT_SUCCESS)
		trace("success");
}

۵ حالت مختلف برای توکن می¬تواند رخ داده باشد. شما می¬توانید تمامی این مقادیر را در کلاس TokenVerifiedEvent مشاهده نمایید.

    • TokenVerifiedEvent.RESULT_SUCCESS: این مقدار به معنای موفقیت آمیز بودن نمایش تبلیغ بوده است. در این حالت کاربر ویدیو را به صورت کامل دیده است.
    • TokenVerifiedEvent.RESULT_NOT_USED: اطلاعات مربوط به نمایش تبلیغ هنوز توسط سرور دریافت نشده است.
    • TokenVerifiedEvent.RESULT_TOKEN_EXPIRED: توکن مربوطه منقضی شده است.
    • TokenVerifiedEvent.RESULT_TOKEN_NOT_FOUND: توکن مربوطه در سرور وجود ندارد.
    • TokenVerifiedEvent.RESULT_INTERNAL_ERROR: در صورت قطع بودن اتصال به اینترنت و یا بروز هرگونه خطا در ارتباط کتابخانه با سرور این مقدار برگردانده خواهد شد.

نمایش تبلیغ جهت تست :

tapligh.setTestEnable(boolean);

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

فراموش نکنید که حتما قبل از انتشار نهایی برنامه خود این مقدار را false کنید. به خاطر بسپارید که کامنت کردن این خط معادل false کردن آن نیست و اگر این خط را کامنت کنید نمایش تپلیغ تست ادامه پیدا خواهد کرد و منجر به عدم درآمدزایی شما از تپلیغ خواهد شد.

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