راه‌اندازی افزایه «تبلیغات تلفن همراه Google» در Unity

پلاتفرم را انتخاب کنید: Android iOS Unity Flutter Android (Legacy)

افزونه Google Mobile Ads Unity به توسعه‌دهندگان Unity امکان می‌دهد آگهی‌های Google Mobile را در برنامه‌های Android و iOS بدون نیاز به نوشتن کد Java یا Objective-C ارائه دهند. افزونه یک میانای C# ‎ برای درخواست آگهی ارائه می‌دهد که توسط اسکریپت‌های C# ‎ در پروژه Unity شما استفاده می‌شود.

این راهنما برای ناشرانی است که می‌خواهند از برنامه Unity درآمدزایی کنند.

پیش‌نیازها

• از Unity Editor نسخه ۲۰۱۹.۴ یا بالاتر استفاده کنید.
  • نسخه ۲۰۲۲.۲ یا بالاتر را توصیه می‌کنیم.
• برای استقرار در iOS
  • ‫Xcode نسخه ۱۶.۰ یا بالاتر
  • iOS نسخه ۱۳.۰ یا بالاتر را هدف قرار دهید
  • CocoaPods
• برای استقرار در Android
  • حداقل سطح ای‌پی‌آی Android نسخه ۲۴ یا بالاتر
  • هدف‌گیری سطح میانای برنامه‌سازی کاربردی Android نسخه ۳۵ یا بالاتر

• توصیه‌شده: ایجاد حساب AdMob و ثبت برنامه Android یا iOS

سطح Android API در تنظیمات پروژه > پخش‌کننده > Android > تنظیمات دیگر > تنظیمات دیگر تنظیم می‌شود.

وارد کردن افزایه «تبلیغات تلفن همراه برای Unity»

OpenUPM-CLI

اگر OpenUPM CLI را نصب کرده‌اید، می‌توانید با فرمان زیر، دفتر ثبت OpenUPM را نصب کنید:

openupm add com.google.ads.mobile

برداشتن .unitypackage دارایی افزایه

اگر از .unitypackage به OpenUPM مهاجرت می‌کنید، باید دارایی‌ها را به‌صورت دستی از مکان قدیمی حذف نصب کنید. فهرست‌های راهنمای زیر را که از .unitypackage وارد شده‌اند بردارید:

• Assets/ExternalDependencyManager
• Assets/GoogleMobileAds
• Assets/Plugins/Android/googlemobileads-unity.aar
• Assets/Plugins/Android/GoogleMobileAdsPlugin
• Assets/Plugins/iOS/GADUAdNetworkExtras
• Assets/Plugins/iOS/unity-plugin-library.a

OpenUPM با واسط کاربر

1. با انتخاب گزینه منو Unity ویرایش > تنظیمات پروژه > مدیر بسته، تنظیمات مدیر بسته را باز کنید.

2. OpenUPM را به‌عنوان یک دفتر ثبت محدودشده به پنجره «مدیر بسته» اضافه کنید:

   Name: OpenUPM
   URL: https://package.openupm.com
   Scopes: com.google
   

3. منو مدیر بسته را با انتخاب گزینه منو Unity پنجره > مدیر بسته باز کنید.

4. منوِ کرکره‌ای دامنه مدیر را روی ثبت‌های من تنظیم کنید.

   

5. بسته Google Mobile Ads for Unity را از فهرست بسته‌ها انتخاب کنید و نصب را فشار دهید.

برداشتن .unitypackage دارایی افزایه

اگر از .unitypackage به OpenUPM مهاجرت می‌کنید، باید دارایی‌ها را به‌صورت دستی از مکان قدیمی حذف نصب کنید. فهرست‌های راهنمای زیر را که از .unitypackage وارد شده‌اند بردارید:

• Assets/ExternalDependencyManager
• Assets/GoogleMobileAds
• Assets/Plugins/Android/googlemobileads-unity.aar
• Assets/Plugins/Android/GoogleMobileAdsPlugin
• Assets/Plugins/iOS/GADUAdNetworkExtras
• Assets/Plugins/iOS/unity-plugin-library.a

OpenUPM

1. برچسب نسخه جدیدترین انتشار را واکشی کنید. برچسب برگردانده‌شده، بدون پیشوند v، نسخه Google Mobile Ads Unity Plugin است.

   • macOS و Linux

     curl -sS https://api.github.com/repos/googleads/googleads-mobile-unity/releases/latest | jq -r '.tag_name'

   • Windows PowerShell

     (Invoke-RestMethod -Uri "https://api.github.com/repos/googleads/googleads-mobile-unity/releases/latest").tag_name
     

2. فایل Packages/manifest.json را اصلاح کنید تا بااستفاده از نسخه به‌دست‌آمده از فرمان قبلی، رجیستری و وابستگی با دامنه OpenUPM را اضافه کنید:

   {
     "scopedRegistries": [
       {
         "name": "google",
         "url": "https://package.openupm.com",
         "scopes": [
           "com.google"
         ]
       }
     ],
     "dependencies": {
       "com.google.ads.mobile": "11.6.0"
     }
   }
   

برداشتن .unitypackage دارایی افزایه

اگر از .unitypackage به OpenUPM مهاجرت می‌کنید، باید دارایی‌ها را به‌صورت دستی از مکان قدیمی حذف نصب کنید. فهرست‌های راهنمای زیر را که از .unitypackage وارد شده‌اند بردارید:

• Assets/ExternalDependencyManager
• Assets/GoogleMobileAds
• Assets/Plugins/Android/googlemobileads-unity.aar
• Assets/Plugins/Android/GoogleMobileAdsPlugin
• Assets/Plugins/iOS/GADUAdNetworkExtras
• Assets/Plugins/iOS/unity-plugin-library.a

وارد کردن از GitHub

1. نسخه .unitypackage را از GitHub بارگیری کنید.
2. فایل .unitypackage را با انتخاب گزینه منو Unity دارایی‌ها > وارد کردن بسته > بسته سفارشی و وارد کردن همه موارد وارد کنید.

اختیاری: غیرفعال کردن External Dependency Manager

اگر کتابخانه‌های Android و iOS را با ابزارهای ساخت خودتان مدیریت می‌کنید، می‌توانید بسته com.unity.external-dependency-manager را غیرفعال کنید:

در Unity Editor، Window > Package Manager را انتخاب کنید و بسته External Dependency Manager (com.unity.external-dependency-manager) را بردارید. با برداشتن این بسته، فعال کردن مدیر وابستگی خارجی در دارایی‌ها > Google Mobile Ads > تنظیمات پاک می‌شود.

توجه: حذف کردن فایل GoogleMobileAdsSettings.asset تنظیمات شما را بازنشانی می‌کند و در بارگذاری بعدی «ویرایشگر» یا وارد کردن بعدی، بسته com.unity.external-dependency-manager را دوباره نصب می‌کند. برای بازنصب کردن بسته در آینده، Assets > Google Mobile Ads > Settings را انتخاب کنید و Enable External Dependency Manager را انتخاب کنید.

نصب «مدیر وابستگی خارجی» قدیمی

اگر پروژه‌تان از Unity 2022.2 یا نسخه‌های قدیمی‌تر استفاده می‌کند، می‌توانید پس‌از غیرفعال کردن بسته Unity، بسته قدیمی com.google.external-dependency-manager Google را نصب کنید:

• جدیدترین فایل .unitypackage را از صفحه نسخه‌های External Dependency Manager for Unity بارگیری کنید و دارایی‌ها > وارد کردن بسته > بسته سفارشی را انتخاب کنید.

• فرمان OpenUPM CLI زیر را اجرا کنید:

  openupm add com.google.external-dependency-manager

پیکربندی دستی وابستگی‌های بومی

اگر از بسته «مدیر وابستگی خارجی» استفاده نمی‌کنید، کتابخانه‌های لازم را از فایل‌های Assets/GoogleMobileAds/Editor/GoogleMobileAdsDependencies.xml و Assets/GoogleMobileAds/Editor/GoogleUmpDependencies.xml به فایل‌های ساخت اضافه کنید:

• برای Android، ویرایش > تنظیمات پروژه > پخش‌کننده > Android > تنظیمات انتشار > ساخت را انتخاب کنید و الگوی Gradle اصلی سفارشی را فعال کنید. کتابخانه‌های موردنیاز را از فایل‌های GoogleMobileAdsDependencies.xml و GoogleUmpDependencies.xml به بلوک dependencies در فایل Assets/Plugins/Android/mainTemplate.gradle اضافه کنید:

  implementation 'com.google.android.gms:play-services-ads:25.5.0'
  implementation 'com.google.android.ump:user-messaging-platform:4.0.0'
  

  همچنین بسته‌های androidx.constraintlayout:constraintlayout، androidx.lifecycle:lifecycle-process، و androidx.fragment:fragment را بااستفاده از نسخه‌های موجود در فایل GoogleMobileAdsDependencies.xml اضافه کنید.

• برای iOS، پروژه Xcode خود را صادر کنید. پادهای لازم را از فایل‌های GoogleMobileAdsDependencies.xml و GoogleUmpDependencies.xml به فایل Podfile در پوشه پروژه صادرشده‌تان اضافه کنید:

  pod 'Google-Mobile-Ads-SDK'
  pod 'GoogleUserMessagingPlatform'
  

  سپس فرمان زیر را در پوشه پروژه iOS صادرشده‌تان اجرا کنید:

  pod install --repo-update

تنظیم شناسه برنامه AdMob

در ویرایشگر Unity، Assets > Google Mobile Ads > Settings را از منو انتخاب کنید.

شناسه برنامه AdMob Android و iOS خود را در هر فیلد وارد کنید.

Google Mobile Ads Unity Plugin این تنظیمات را به‌صورت نوشتار در فایل پیکربندی Assets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset ذخیره می‌کند.

مقداردهی اولیه کیت توسعه نرم‌افزار

قبل‌از بار کردن آگهی‌ها، با فراخوانی MobileAds.Initialize()، Google Mobile Ads Unity Plugin را در برنامه‌تان مقداردهی اولیه کنید. این کار فقط یک‌بار باید انجام شود، ترجیحاً هنگام راه‌اندازی برنامه.

هشدار: آگهی‌ها را می‌توان با Google Mobile Ads Unity Plugin یا کیت توسعه نرم‌افزار شریک میانجی هنگام فراخوانی MobileAds.Initialize() پیش‌بارگیری کرد. اگر لازم است از کاربران ساکن منطقه اقتصادی اروپا (EEA)، پادشاهی متحد (UK)، یا سوئیس رضایت بگیرید، پرچم‌های خاص درخواست را تنظیم کنید، مثلاً tagForChildDirectedTreatment یا tag_for_under_age_of_consent، یا قبل‌از بار کردن آگهی‌ها اقدام دیگری انجام دهید. مطمئن شوید که این کار را قبل‌از مقداردهی اولیه Google Mobile Ads Unity Plugin انجام می‌دهید.

در اینجا مثالی از نحوه فراخوانی MobileAds.Initialize() آورده شده است:

MobileAds.Initialize((InitializationStatus initstatus) =>
{
    if (initstatus == null)
    {
        Debug.LogError("Google Mobile Ads initialization failed.");
        return;
    }

    Debug.Log("Google Mobile Ads initialization complete.");

    MobileAdsEventExecutor.ExecuteInUpdate(() =>
    {
        // Interact with UnityEngine objects on the main thread here.
    });
});
GoogleMobileAdsController.cs

تعامل با اشیاء Unity در رشته اصلی

Google Mobile Ads Unity Plugin رویدادهای آگهی را در رشته پس‌زمینه مطرح می‌کند. اگر فراخوانی‌های برگشتی آگهی با اشیای Unity، مثل UnityEngine، تعامل دارند، صریحاً آن کار را بااستفاده از روش MobileAdsEventExecutor.ExecuteInUpdate در رشته اصلی Unity زمان‌بندی کنید. برای جزئیات پیاده‌سازی، Raise ad events on the Unity main thread (افزایش رویدادهای آگهی در رشته اصلی Unity) را ببینید.

انتخاب قالب آگهی

Google Mobile Ads Unity Plugin اکنون در برنامه Unity شما گنجانده شده است، وقتی که در پلاتفرم Android یا iOS مستقر می‌شود. اکنون آماده پیاده‌سازی آگهی هستید. AdMob قالب‌های آگهی مختلفی ارائه می‌دهد تا بتوانید قالبی را انتخاب کنید که بهترین تجربه کاربری را ایجاد می‌کند.

برنما

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

پیاده‌سازی آگهی‌های برنما

بینابینی

واحدهای آگهی بینابینی آگهی‌های تمام‌صفحه را در برنامه‌تان نشان می‌دهند. آن‌ها را در وقفه‌ها و انتقال‌های طبیعی در میانای برنامه‌تان قرار دهید، مثلاً پس‌از تکمیل سطح در برنامه بازی.

پیاده‌سازی آگهی‌های بینابینی

بومی

آگهی‌های بومی آگهی‌هایی هستند که می‌توانید نحوه ارائه دارایی‌هایی مثل عنوان‌ها و دعوت به اقدام‌ها را در برنامه‌هایتان سفارشی‌سازی کنید. با سبک‌بندی آگهی توسط خودتان، می‌توانید ارائه آگهی طبیعی و غیرمزاحمی ایجاد کنید که می‌تواند به تجربه کاربری غنی اضافه کند.

پیاده‌سازی آگهی‌های بومی

پاداش

واحدهای آگهی دارای پاداش به کاربران امکان می‌دهند بازی کنند، در نظرسنجی‌ها شرکت کنند، یا ویدیو تماشا کنند تا پاداش‌های درون‌برنامه‌ای مثل سکه، جان اضافی، یا امتیاز کسب کنند. می‌توانید پاداش‌های مختلفی برای واحدهای آگهی مختلف تنظیم کنید و مقادیر پاداش و مواردی را که کاربر دریافت می‌کند مشخص کنید.

پیاده‌سازی آگهی‌های پاداش‌دار

بینابینی پاداش‌دار

آگهی بینابینی پاداش‌دار نوع جدیدی از قالب آگهی تشویقی است که به شما امکان می‌دهد برای آگهی‌هایی که به‌طور خودکار درطول انتقال‌های طبیعی برنامه ظاهر می‌شوند، پاداش‌هایی مانند سکه یا جان اضافی ارائه دهید.

برخلاف آگهی‌های پاداش‌دار، کاربران برای مشاهده آگهی بینابینی پاداش‌دار ملزم به موافقت کردن نیستند.

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

پیاده‌سازی آگهی‌های بینابینی پاداش‌دار

صفحه باز شدن برنامه

«باز کردن برنامه» قالب آگهی‌ای است که وقتی کاربران برنامه شما را باز می‌کنند یا به آن برمی‌گردند ظاهر می‌شود. آگهی روی صفحه بار کردن قرار می‌گیرد.

پیاده‌سازی آگهی در صفحه باز شدن برنامه