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

این متن جهت آماده‌سازی و استفاده از کتابخانه مگنت در برنامه کاربردی اندروید شما تهیه شده است. در صورت داشتن هر گونه سوال، از طریق پست الکترونیک 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، تستی از عملکرد مگنت روی پروژه خود داشته باشید.

آیا این متن توانست به شما کمک کند؟
آیا این متن توانست به شما کمک کند؟
راهنمای یونیتی