راه اندازی تپسل پلاس در یونیتی (Android)

در صورت وجود مشکل یا ابهام به لیست خطاهای فنی رایج مراجعه کنید یا صفحه‌ی Github Issues را بررسی نمایید.

اضافه کردن Unity Package تپسل پلاس

برای اضافه کردن تپسل پلاس ۲ روش وجود دارد. در صورتیکه تمایل به استفاده از کتابخانه جدید تپسل پلاس (از نسخه ۲.۱.۸ یا بالاتر) را دارید، لطفا از روش ۲ (Resolver) استفاده نمایید.

۱. استفاده از Gradle

۱. ابتدا unitypackage تپسل پلاس را از این لینک دریافت نمایید. ۲. از طریق منوی زیر unitypackage تپسل پلاس را به پروژه‌ی خود اضافه نمایید. (اگر فولدر TapsellPlus از قبل در پروژه‌ی شما وجود دارد لطفا آن را پاک کنید)

Assets > Import Package > Custom Package...

۳. از طریق منوهای زیر، تیک‌های مربوط به ایجاد فایل‌های Custom Gradle را بزنید:

Edit > Project Setting... > Player > Publishing Settings > Custom Launcher Gradle Template
Edit > Project Setting... > Player > Publishing Settings > Custom Main Gradle Template
Edit > Project Setting... > Player > Publishing Settings > Custom Base Gradle Template
Edit > Project Setting... > Player > Publishing Settings > Custom Gradle Properties Template

۴. برای فعال سازی AndroidX در پروژه، به آدرس Assets\Plugins\Android\gradle.properties بروید و قطعه کد زیر را اضافه کنید:

android.useAndroidX=true
android.enableJetifier=true

۵. به آدرس Assets\Plugins\Android\mainTemplate.gradle بروید و :خط کامنت شده‌ی بالای فایل را حذف نمایید

// GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN

سپس در بخش dependencies خط زیر را اضافه نمایید:

dependencies {
    ...
    implementation 'ir.tapsell.plus:tapsell-plus-sdk-unity:2.1.7'
    ...
**DEPS**}

اگر تکه کد زیر نیز در فایل وجود نداشت آن را اضافه نمایید:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

۶. اگر از نسخه یونیتی ۲۰۱۹ و پایین‌تر استفاده می‌کنید لطفا به آدرس Assets\Plugins\Android\baseProjectTemplate.gradle بروید و عبارت mavenCentral() را به هر دو بخش repositories اضافه نمایید. سپس ورژن com.android.tools.build:gradle را به ۳.۶.۰ تغییر دهید.

دقت داشته باشید که استفاده از ورژن ۳.۶.۰ برای Android Gradle Plugin تنها در صورتیکه از نسخه یونیتی ۲۰۱۹ و پایین‌تر استفاده میکنید الزامی است. زیرا برای پشتیبانی از اندروید یازده می‌بایستی حداقل از این ورژن در پروژه پشتیبانی شود. برای اضافه کردن نسخه‌ای از Gradle که قابلیت پشتیبانی از اندروید یازده را دارد، می‌توانید از این لینک کمک بگیرید.

۱۰. بعد از اضافه کردن تپسل پلاس و شبکه‌های تبلیغاتی دیگر احتمالا به دلیل بالا رفتن حجم کد و جلوگیری از وقوع خطای زیر می‌بایستی MultiDex را فعال نمایید. در صورتیکه از minSdkVersion نسخه‌ی ۲۱ یا بالاتر استفاده میکنید، MultiDex به صورت پیش فرض فعال است. در غیر اینصورت لازم است آن را به صورت دستی به پروژه خود اضافه نمایید.

D8: Cannot fit requested classes in a single dex file (# methods: 68109 > 65536)

نحوه‌ی فعال‌سازی MultiDex به این ترتیب است که به آدرس Assets\Plugins\Android\launcherTemplate.gradle بروید و کدهای زیر را به آن اضافه نمایید:

dependencies {
    def multidex_version = "2.0.1"
    implementation "androidx.multidex:multidex:$multidex_version" // 2.0.1
}

android {
  ...
  defaultConfig {
    ...
    multiDexEnabled true
  }
  ...
}

سپس به فایل Assets\Plugins\Android\AndroidManifest.xml مراجعه کنید و یکی از روش های الف، ب و ج را مطابق پیاده‌سازی خود اعمال نمایید.

الف) در صورتیکه قبلا از کلاس Application در پروژه خود استفاده نکرده اید، خط زیر را در تگ application اضافه کنید:

<application
  android:name="androidx.multidex.MultiDexApplication" >
  <!--  ...-->
</application>

ب) در غیر اینصورت اگر قبلا از کلاس Application در پروژه خود استفاده کرده اید و آن را در AndroidManifest.xml معرفی کرده‌اید، وارد کلاس Application شده و آن را از کلاس MultiDexApplication ارث بری کنید. تغییرات مورد نیاز را همانند کد زیر اعمال کنید:

public class MainApplication extends MultiDexApplication {
  // your code
}

ج) اما در صورتیکه کلاس Application خود را از کلاس دیگری ارث بری نموده‌اید و امکان ارث بری از کلاس MultiDexApplication وجود ندارد، میتوانید متود attachBaseContext را به صورت زیر در کلاس خود override نمایید و تغییرات لازم را اعمال نمایید:

public class MainApplication extends SomeOtherApplication {
    // your code
    
    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        MultiDex.install(this);
    }
}

برای راهنمایی بهتر می‌توانید به مستندات رسمی اندروید مراجعه نمایید.

۲. استفاده از Resolver

۱. ابتدا فایل unitypackage resolver را دانلود کنید. سپس مطابق توضیحات لینک زیر آن را به پروژه‌ی خود اضافه نمایید:

مستندات گوگل

۲. از طریق منوهای زیر، تیک مربوط به Jetifier و Auto Resolution را بزنید. (تیک مربوط به Auto Resolution اجباری نیست اما برای آن که هر بار مجبور نباشید کتابخانه‌ها را به شکل دستی Resolve کنید بهتر است آن را فعال کنید)

Assets > External Dependency Manager > Android Resolver > Settings > Use Jetifier
Assets > External Dependency Manager > Android Resolver > Settings > Enable Auto-Resolution

۳. ابتدا unitypackage تپسل پلاس را از این لینک دریافت نمایید.

۴. از طریق منوی زیر unitypackage تپسل پلاس را به پروژه‌ی خود اضافه نمایید. (اگر فولدر TapsellPlusSDK از قبل در پروژه‌ی شما وجود دارد لطفا آن را پاک کنید)

Assets > Import Package > Custom Package...

۵. برای اطمینان از اضافه شدن پلاگین تپسل پلاس از طریق منوی زیر اقدام به Resolve کردن کتابخانه‌ها کنید:

Assets > External Dependency Manager > Android Resolver > Force Resolve

۶. از طریق منوهای زیر، تیک‌های مربوط به ایجاد فایل‌های Custom Gradle را بزنید:

Edit > Project Setting... > Player > Publishing Settings > Custom Launcher Gradle Template
Edit > Project Setting... > Player > Publishing Settings > Custom Base Gradle Template
Edit > Project Setting... > Player > Publishing Settings > Custom Gradle Properties Template

۴. برای فعال سازی AndroidX در پروژه، به آدرس Assets\Plugins\Android\gradle.properties بروید و قطعه کد زیر را اضافه کنید:

android.useAndroidX=true
android.enableJetifier=true

۸. اگر تکه کد زیر در آدرس Assets\Plugins\Android\launcherTemplate.gradle وجود نداشت آن را اضافه نمایید:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

۹. به آدرس Assets\Plugins\Android\baseProjectTemplate.gradle بروید و عبارت mavenCentral() را به هر دو بخش repositories اضافه نمایید. سپس ورژن com.android.tools.build:gradle را به ۴.۲.۲ تغییر دهید.

دقت داشته باشید که استفاده از ورژن ۳.۶.۰ برای Android Gradle Plugin الزامی است. زیرا برای پشتیبانی از اندروید یازده می‌بایستی حداقل از این ورژن در پروژه پشتیبانی شود. برای اضافه کردن نسخه‌ای از Gradle که قابلیت پشتیبانی از اندروید یازده را دارد، می‌توانید از این لینک کمک بگیرید.

۱۰. بعد از اضافه کردن تپسل پلاس و شبکه‌های تبلیغاتی دیگر احتمالا به دلیل بالا رفتن حجم کد و جلوگیری از وقوع خطای زیر می‌بایستی MultiDex را فعال نمایید. در صورتیکه از minSdkVersion نسخه‌ی ۲۱ یا بالاتر استفاده میکنید، MultiDex به صورت پیش فرض فعال است. در غیر اینصورت لازم است آن را به صورت دستی به پروژه خود اضافه نمایید.

D8: Cannot fit requested classes in a single dex file (# methods: 68109 > 65536)

نحوه‌ی فعال‌سازی MultiDex به این ترتیب است که به آدرس Assets\Plugins\Android\launcherTemplate.gradle بروید و کدهای زیر را به آن اضافه نمایید:

dependencies {
    def multidex_version = "2.0.1"
    implementation "androidx.multidex:multidex:$multidex_version" // 2.0.1
}

android {
  ...
  defaultConfig {
    ...
    multiDexEnabled true
  }
  ...
}

سپس به فایل Assets\Plugins\Android\AndroidManifest.xml مراجعه کنید و یکی از روش های الف، ب و ج را مطابق پیاده‌سازی خود اعمال نمایید.

الف) در صورتیکه قبلا از کلاس Application در پروژه خود استفاده نکرده اید، خط زیر را در تگ application اضافه کنید:

<application
  android:name="androidx.multidex.MultiDexApplication" >
  <!--  ...-->
</application>

ب) در غیر اینصورت اگر قبلا از کلاس Application در پروژه خود استفاده کرده اید و آن را در manifest معرفی کرده‌اید، وارد کلاس Application شده و آن را از کلاس MultiDexApplication ارث بری کنید. تغییرات مورد نیاز را همانند کد زیر اعمال کنید:

public class MainApplication extends MultiDexApplication {
  // your code
}

ج) اما در صورتیکه کلاس Application خود را از کلاس دیگری ارث بری نموده‌اید و امکان ارث بری از کلاس MultiDexApplication وجود ندارد، میتوانید متود attachBaseContext را به صورت زیر در کلاس خود override نمایید و تغییرات لازم را اعمال نمایید:

public class MainApplication extends SomeOtherApplication {
    // your code
    
    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        MultiDex.install(this);
    }
}

برای راهنمایی بهتر می‌توانید به مستندات رسمی اندروید مراجعه نمایید.

مقداردهی اولیه

ابتدا برای دسترسی به کدهای تپسل از تکه کد زیر استفاده کنید.

using TapsellPlusSDK;

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

TapsellPlus.Initialize(TAPSELLPLUS_KEY,
            adNetworkName => Debug.Log(adNetworkName + " Initialized Successfully."),
            error => Debug.Log(error.ToString()));

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

اکنون می‌توانید با توجه به نیاز خود و توضیحات به هر نوع تبلیغ، تبلیغ مورد نظر را نمایش دهید.

تنظیمات مربوط به GDPR

از آن‌جا که کتابخانه‌ی تپسل پلاس قوانین GDPR را در خصوص نمایش تبلیغات شخصی‌سازی شده رعایت می‌کند، به طور پیش فرض اگر کاربر با IP یکی از کشورهای مشمول این قانون از اپلیکیشن شما استفاده کند، دیالوگی در این خصوص به کاربر نمایش می‌دهد. اگر تمایل دارید تا به جای تصمیم کاربر، خودتان دسترسی لازم را تعیین کنید می‌توانید از تکه کد زیر استفاده نمایید. توجه داشته باشید که این تکه کد می‌بایستی پس از Initialize شدن تپسل پلاس و پیش از درخواست تبلیغ صدا زده شود تا نتیجه‌ی آن در درخواست شما اعمال شده باشد. مقدار true‌ به این معنی است که شما حق استفاده از اطلاعات جهت نمایش تبلیغ شخصی‌سازی شده را به شبکه‌های تبلیغاتی داده‌اید.

TapsellPlus.SetGdprConsent(true);

پروژه‌ی نمونه

برای راهنمایی بیش‌تر می‌توانید از پروژه‌های نمونه‌ی ما بر روی Github استفاده نمایید.