پرش به مطلب اصلی

تنظیمات پایه

شروع​

برای یکپارچه‌سازی Adtrace SDK در پروژه Unity خود، این مراحل را دنبال کنید.

دریافت SDK​

از نسخه 2.0.1 به بعد، می‌توانید آخرین نسخه Adtrace SDK را از صفحه releases اضافه کنید.

اضافه کردن SDK به پروژه​

پروژه را در Unity Editor باز کنید، به Assets → Import Package → Custom Package بروید و فایل Unity package دانلودشده را انتخاب کنید.

یکپارچه‌سازی SDK در اپلیکیشن​

Prefab را از Assets/AdTrace/AdTrace.prefab به اولین scene اضافه کنید.

می‌توانید پارامترهای اسکریپت Adtrace را در Inspector menu prefab ویرایش کنید تا گزینه‌های زیر را تنظیم کنید:

  • Start Manually
  • Event Buffering
  • Send In Background
  • Launch Deferred Deeplink
  • App Token
  • Log Level
  • Environment

{YourAppToken} را با App Token واقعی خود جایگزین کنید. می‌توانید آن را در پنل adtrace بیابید.

بسته به اینکه اپلیکیشن را برای تست یا production می‌سازید، تنظیم Environment را به Sandbox یا Production تغییر دهید.

مهم

مقدار را روی Sandbox تنظیم کنید اگر شما یا شخص دیگری در حال تست اپلیکیشن است. قبل از انتشار، حتماً environment را به Production تغییر دهید. اگر دوباره شروع به تست کردید، به Sandbox برگردید. همچنین توجه داشته باشید که به‌طور پیش‌فرض پنل Adtrace ترافیک production اپلیکیشن را نمایش می‌دهد، پس در صورت نیاز به مشاهده ترافیک sandbox، نمای sandbox را در پنل انتخاب کنید.

از تنظیم environment برای تمییز دادن ترافیک واقعی از ترافیک مصنوعی استفاده می‌کنیم. تنظیم environment را همیشه به‌روز نگه دارید.

اگر نمی‌خواهید Adtrace SDK به‌طور خودکار با رویداد Awake اپلیکیشن شروع کند، Start Manually را انتخاب کنید. با این گزینه، Adtrace SDK را با فراخوانی متد AdTrace.start و ارسال شیء AdTraceConfig از کد راه‌اندازی می‌کنید.

یک scene نمونه با منوی دکمه در اینجا می‌یابید: Assets/AdTrace/ExampleGUI/ExampleGUI.unity.

کد منبع این scene در Assets/AdTrace/ExampleGUI/ExampleGUI.cs قرار دارد.

لاگ‌های Adtrace​

می‌توانید با تغییر مقدار Log Level به یکی از موارد زیر، سطح دقت لاگ‌ها را کم یا زیاد کنید:

  • Verbose - فعال‌سازی همه لاگ‌ها
  • Debug - غیرفعال کردن verbose logs
  • Info - غیرفعال کردن debug logs (پیش‌فرض)
  • Warn - غیرفعال کردن info logs
  • Error - غیرفعال کردن warning logs
  • Assert - غیرفعال کردن error logs
  • Suppress - غیرفعال کردن همه لاگ‌ها

اگر می‌خواهید هنگام راه‌اندازی دستی Adtrace SDK همه خروجی لاگ را غیرفعال کنید، سطح لاگ را روی suppress تنظیم کنید و از constructor شیء AdTraceConfig استفاده کنید:

string appToken = "{YourAppToken}";
AdTraceEnvironment environment = AdTraceEnvironment.Sandbox;

AdTraceConfig config = new AdTraceConfig(appToken, environment, true);
config.setLogLevel(AdTraceLogLevel.Suppress);

AdTrace.start(config);

اگر target شما مبتنی بر Windows است و می‌خواهید لاگ‌های کامپایل‌شده کتابخانه را در حالت released ببینید، خروجی لاگ را به اپلیکیشن هنگام تست در حالت debug ریدایرکت کنید.

متد setLogDelegate را روی instance AdTraceConfig قبل از راه‌اندازی SDK فراخوانی کنید:

//...
adtraceConfig.setLogDelegate(msg => Debug.Log(msg));
//...
AdTrace.start(adtraceConfig);

Google Play Services​

از اول اگوست ۲۰۱۴، اپلیکیشن‌های موجود در Google Play Store باید از Google Advertising ID استفاده کنند. برای اینکه Adtrace SDK از Google Advertising ID استفاده کند، Google Play Services را یکپارچه کنید. پوشه google-play-services_lib (بخشی از Android SDK) را در پوشه Assets/Plugins/Android پروژه Unity کپی کنید.

دو روش اصلی برای دانلود Android SDK وجود دارد. هر ابزاری که از Android SDK Manager استفاده می‌کند لینک سریعی برای دانلود و نصب ابزارهای Android SDK ارائه می‌دهد. پس از نصب، کتابخانه‌ها را در پوشه SDK_FOLDER/extras/google/google_play_services/libproject/ می‌یابید.

می‌توانید فقط بخشی از Google Play Services که Adtrace SDK به آن نیاز دارد را اضافه کنید. فایل play-services-basement-x.y.z.aar را به پوشه Assets/Plugins/Android اضافه کنید.

با Google Play Services library نسخه 15.0.0، گوگل کلاس‌های مورد نیاز برای دریافت Google advertising ID را به پکیج play-services-ads-identifier منتقل کرده. اگر از نسخه 15.0.0 یا بالاتر استفاده می‌کنید این پکیج را اضافه کنید.

دانلود Google play services ads identifier: maven , direct link

اضافه کردن مجوز برای دریافت Google advertising ID​

اگر Android 12 و بالاتر (API level 31) را هدف می‌گیرید، باید مجوز com.google.android.gms.AD_ID را اضافه کنید. این کار به‌طور خودکار در فرایند post-build انجام نمی‌شود. خط زیر را به AndroidManifest.xml اضافه کنید:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

برای اطلاعات بیشتر، مستندات AdvertisingIdClient.Info گوگل را ببینید.

تست برای Google advertising ID​

برای بررسی اینکه Adtrace SDK Google advertising ID را دریافت می‌کند، اپلیکیشن را در حالت sandbox با سطح لاگ verbose اجرا کنید. سپس یک Session یا Event ردیابی کنید و لیست پارامترهای ثبت‌شده در verbose logs را بررسی کنید. اگر پارامتر gps_adid را دیدید، SDK با موفقیت Google advertising ID را خوانده.

تنظیمات Proguard​

اگر از Proguard استفاده می‌کنید، این خطوط را به فایل Proguard اضافه کنید:

-keep class io.adtrace.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }

Google Install Referrer​

برای اتریبیوشن نصب اپلیکیشن Android، Adtrace به اطلاعات Google install referrer نیاز دارد. می‌توانید از Google Play Referrer API یا Google Play Store intent با broadcast receiver استفاده کنید.

Google Install Referrer API برای ارائه روشی مطمئن‌تر و امن‌تر معرفی شد. Google Play Store intent به‌طور موازی با API به‌صورت موقت وجود دارد، اما قرار است در آینده منسوخ شود.

فرایند post-build Adtrace Google Play Store intent را دریافت می‌کند؛ می‌توانید چند مرحله اضافی برای پشتیبانی از Google Play Referrer API جدید انجام دهید.

برای پشتیبانی از Google Play Referrer API، کتابخانه install referrer را از Maven repository یا direct link دانلود کنید و فایل AAR را در Plugins/Android قرار دهید.

Huawei Referrer API​

از نسخه v2.0.1، Adtrace SDK از ردیابی نصب روی دستگاه‌های Huawei با نسخه Huawei App Gallery 10.4 و بالاتر پشتیبانی می‌کند. برای اطلاعات بیشتر نحوه استفاده از oaid native plugin را ببینید.

فرایند post-build​

برای تکمیل فرایند build اپلیکیشن، پکیج Unity Adtrace اقدامات post-build سفارشی انجام می‌دهد تا SDK بتواند به‌درستی در اپلیکیشن کار کند.

این فرایند توسط متد OnPostprocessBuild در AdTraceEditor.cs انجام می‌شود. پیام‌های خروجی لاگ در پنجره کنسول Unity IDE نوشته می‌شوند.

فرایند post-build برای iOS​

برای اجرای صحیح فرایند post-build iOS، از Unity 5 یا بالاتر با نصب iOS build support استفاده کنید. فرایند post-build iOS تغییرات زیر را در پروژه Xcode تولیدشده اعمال می‌کند:

  • اضافه می‌کند iAd.framework (برای ردیابی Apple Search Ads)
  • اضافه می‌کند AdServices.framework (برای ردیابی Apple Search Ads)
  • اضافه می‌کند AdSupport.framework (برای خواندن IDFA)
  • اضافه می‌کند CoreTelephony.framework (برای خواندن نوع شبکه دستگاه)
  • اضافه می‌کند other linker flag یعنی -ObjC (برای تشخیص Adtrace Objective-C categories در زمان build)
  • فعال می‌کند Objective-C exceptions

در صورت فعال‌سازی پشتیبانی iOS 14+ (Assets/AdTrace/Toggle iOS 14 Support)، فرایند post-build iOS دو فریم‌ورک اضافی به پروژه Xcode شما اضافه می‌کند:

  • اضافه می‌کند AppTrackingTransparency.framework (برای درخواست رضایت کاربر)
  • اضافه می‌کند StoreKit.framework (برای ارتباط با فریم‌ورک SKAdNetwork)

فرایند post-build برای Android​

فرایند post-build Android تغییراتی در فایل AndroidManifest.xml واقع در Assets/Plugins/Android/ اعمال می‌کند. همچنین وجود فایل AndroidManifest.xml را در پوشه Android plugins بررسی می‌کند. اگر فایل وجود نداشت، یک نسخه از فایل manifest سازگار AdTraceAndroidManifest.xml ایجاد می‌کند. اگر AndroidManifest.xml از قبل وجود داشت، تغییرات زیر را اعمال می‌کند:

  • اضافه می‌کند مجوز INTERNET
  • اضافه می‌کند مجوز ACCESS_WIFI_STATE
  • اضافه می‌کند مجوز ACCESS_NETWORK_STATE
  • اضافه می‌کند مجوز BIND_GET_INSTALL_REFERRER_SERVICE
  • اضافه می‌کند Adtrace broadcast receiver
یادداشت

اگر از broadcast receiver خودتان برای مدیریت INSTALL_REFERRER intent استفاده می‌کنید، نیازی به اضافه کردن Adtrace broadcast receiver به manifest نیست. آن را حذف کنید، اما فراخوانی Adtrace broadcast receiver را داخل receiver خودتان اضافه کنید، همان‌طور که در راهنمای Android توضیح داده شده.