راهنمای یونیتی

این متن جهت آماده‌سازی و استفاده از کتابخانه مگنت در برنامه کاربردی اندروید شما تهیه شده است. در صورت داشتن هر گونه سوال، از طریق پست الکترونیک info@magnet.ir آن را با ما در میان بگذارید.

---

۱- پیش‌نیاز‌ها

۱-۱- افزودن پلاگین

اولین قدم در استفاده از سامانه تبلیغاتی مگنت، افزودن پلاگین مگنت به پروژه یونیتی است. برای این منظور ابتدا پلاگین یونیتی مگنت را از اینجا دانلود کنید و از طریق منوی زیر به پروژه خود اضافه کنید:

Assets > Import Package > Custom Package

۱-۲- تنظیمات manifest

در این مرحله باید مجوزهای لازم و تنظیمات اولیه برای نمایش تبلیغ را در فایل AndroidManifest.xml قرار دهید. برای این منظور ابتدا permissionهای زیر را در بخش manifest فایل AndroidManifest.xml اضافه کنید:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <!--optional-->

در گام بعد activity زیر را در بخش application اضافه کنید:

<activity android:name="com.magnetadservices.sdk.MagnetInterstitialActivity"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:hardwareAccelerated="true">
</activity>

۲- راه‌اندازی سیستم تبلیغ

۲-۱- ساخت prefab

در این مرحله ابتدا یک prefab مربوط به تبلیغات مگنت را در پروژه خود ایجاد و قطعه کد زیر را در متد Start() اسکریپت مربوط به آن اضافه کنید:

Magnet.GetDefaultPlugin().Initialize();
Magnet.GetDefaultPlugin().SetTestMode(true);

• متد SetTestMode() حالت تست SDK را فعال یا غیر فعال می‌کند. برای تست برنامه خود این حالت را فعال و قبل از انتشار برنامه غیر فعال کنید.

۲-۲- Interstitial

برای دریافت تبلیغ میانی از توابع زیر استفاده کنید:

Magnet.GetDefaultPlugin().SetInterstitialAdListener("YOUR_PREFAB_NAME");
Magnet.GetDefaultPlugin().LoadInterstitial("YOUR_ADUNIT_ID");

• در این کد به جای YOUR_PREFAB_NAME نام prefab که برای نمایش تبلیغات مگنت ساخته‌اید را قرار دهید.
• به جای YOUR_ADUNIT_ID شناسه‌ای که در هنگام ساخت رسانه در پنل مگنت دریافت کرده‌اید را قرار دهید.

۲-۳- Rewarded

برای دریافت تبلیغ جایزه‌دار از توابع زیر استفاده کنید:

Magnet.GetDefaultPlugin().SetRewardAdListener("YOUR_PREFAB_NAME");
Magnet.GetDefaultPlugin().LoadRewarded("YOUR_ADUNIT_ID");

• در این کد به جای YOUR_PREFAB_NAME نام prefabی که برای نمایش تبلیغات مگنت ساخته‌اید را قرار دهید.
• به جای YOUR_ADUNIT_ID شناسه‌ای که در هنگام ساخت رسانه در پنل مگنت دریافت کرده‌اید را قرار دهید.

۲-۴- دریافت event مگنت

برای دریافت event های مگنت، متد زیر را درون کلاس اسکریپت مربوط به prefab اضافه کنید:

public void onMagnetEventReceived(string strEvent) {}

لازم به ذکر است که آرگومان strEvent در این متد می‌تواند سه مقدار زیر را دارا باشد:

Magnet.ReceivedEvent, Magnet.LoadFailed, Magnet.Closed, Magnet.Finished

۲-۴-۱- آماده بودن تبلیغ برای نمایش

دریافت event اول (Magnet.ReceivedEvent) به این معناست که تبلیغی برای نمایش load شده است و شما می‌توانید متناسب با تبلیغی که درخواست کردید آن را نمایش دهید.

Magnet.GetDefaultPlugin().ShowInterstitial();
Magnet.GetDefaultPlugin().ShowRewarded();

۲-۴-۲- دریافت نکردن تبلیغ

دریافت event دوم (Magnet.LoadFailed) به این معناست که در هنگام دریافت تبلیغ خطایی رخ داده است و تبلیغی برای نمایش وجود ندارد.

۲-۴-۳- بسته شدن تبلیغ

دریافت event سوم (Magnet.Closed) به این معناست که تبلیغ در حال نمایش توسط کاربر بسته شده و کاربر به محیط برنامه شما بازگشته است.

۲-۴-۴- اتمام نمایش تبلیغ جایزه‌ای

این رویداد فقط برای تبلیغات جایزه‌ای رخ می‌دهد و برای تبلیغات میانی لزومی به پیاده‌سازی این بخش نیست. دریافت event چهارم (Magnet.Finished) به این معناست که نمایش تبلیغ جایزه‌ای به پایان رسیده است و بر اساس مقداری که برگردانده‌شده می‌توانید متوجه شوید که نمایش تبلیغ کامل انجام شده است یا خیر. اگر مقدار آن true باشد، تبلیغ کامل دیده شده و می‌توانید به کاربر جایزه (reward) بدهید، در غیر این صورت تبلیغ کامل دیده نشده و فرآیند دادن جایزه نباید صورت بگیرد و می‌توانید منطق خود را برای این رویداد پیاده‌سازی کنید. (مثلا پیغام دهید که برای دریافت جایزه یا سنگ رایگان باید ویدیو تبلیغاتی را تا انتها مشاهده کنید.)

۲-۴-۵- پیاده‌سازی متد onMagnetEventReceived برای تبلیغ جایزه‌دار

public void onMagnetEventReceived(string strEvent) {
    if (strEvent.Contains(Magnet.ReceivedEvent)) {
        Magnet.GetDefaultPlugin().ShowRewarded();
    }

    if (strEvent.Contains(Magnet.Finished)) {
        string[] split = strEvent.Split(Delimeter);
        bool isRewardSuccessful;
        Boolean.TryParse(split[1], out isRewardSuccessful);

        print("isRewardSuccessful: " + isRewardSuccessful);
        if (isRewardSuccessful) {
            // reward successful logic
        }
        else {
            // reward unsuccessful logic
        }
    }

    if (strEvent.Contains(Magnet.Preloaded)) {
        // only for rewarded ad
        // ad preloaded now you can call the Magnet.GetDefaultPlugin().RetrieveData() to show the preloaded ad
    }

    if (strEvent.Contains(Magnet.LoadFailed)) {
        char delimeter = '|';
        string[] split = strEvent.Split(delimeter);
        string errorCode = split[1];
        string errorMessage = split[2];

        // ad load failed
    }

    if (strEvent.Contains(Magnet.Closed)) {
        // when ad is closed
    }
}

۲-۵- نمونه پیاده‌سازی مگنت

همچنین پلاگین یونیتی مگنت که دریافت کرده‌اید، شامل یک prefab تست، با پیاده‌سازی ساده‌ای از رویدادها، با نام MagnetPlugin و فایل AndroidManifest.xml شامل تمام پیش‌نیازهای مگنت است. شما می‌توانید پس از اضافه کردن این plugin به پروژه، کشیدن MagnetPlugin به صحنه نمایش و قرار دادن AdUnitId خود در LoadInterstitial در متد Start از اسکریپت MagnetPlugin، تستی از عملکرد مگنت روی پروژه خود داشته باشید.

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