سؤالات متداول (FAQ)
سؤالات رایج درباره یکپارچهسازی Unity، تست، ردیابی Event و عیبیابی.
یکپارچهسازی
چطور Unity SDK را اضافه کنم؟
آخرین .unitypackage را از صفحه releases دانلود کنید، سپس در Unity Editor به Assets → Import Package → Custom Package بروید و فایل را انتخاب کنید.
Assets/AdTrace/AdTrace.prefab را به اولین scene اضافه کنید. توکن اپلیکیشن، environment و سطح لاگ را در Inspector prefab پیکربندی کنید. برای راهنمای کامل Basic Setup را ببینید.
آیا SDK باید بهطور خودکار شروع کند یا دستی؟
بهطور پیشفرض، prefab SDK را در رویداد Awake scene راهاندازی میکند. اگر نیاز دارید زمانبندی را کنترل کنید: مثلاً پس از رضایت کاربر یا بارگذاری config: Start Manually را روی prefab فعال کرده و AdTrace.start(config) را از کد خود هنگام آمادگی فراخوانی کنید:
AdTraceConfig config = new AdTraceConfig("{YourAppToken}", AdTraceEnvironment.Sandbox);
config.setLogLevel(AdTraceLogLevel.Verbose);
AdTrace.start(config);
از یک مسیر شروع ثابت استفاده کنید؛ AdTrace.start را بیش از یک بار در هر بار اجرای اپلیکیشن فراخوانی نکنید.
چه تنظیمات Android ضروری است؟
پکیج Unity یک فرایند post-build برای پیکربندی native اجرا میکند، اما همچنان نیاز دارید:
- Google Play Services (از جمله
play-services-ads-identifierبرای نسخههای اخیر کتابخانه) درAssets/Plugins/Android. - مجوز
com.google.android.gms.permission.AD_IDدرAndroidManifest.xmlبرای Android 12+. - فایل AAR کتابخانه install referrer در
Plugins/Androidبرای اتریبیوشن کمپین مطمئن. - قوانین ProGuard keep هنگام فعالسازی minification.
جزئیات در Basic Setup موجود است.
تست
چرا دادهای در پنل نمیبینم؟
| دلیل | راهحل |
|---|---|
| عدم تطابق environment | environment prefab یا config را در هنگام تست روی Sandbox تنظیم کنید. پنل را به ترافیک sandbox تغییر دهید: production نمای پیشفرض است. |
| دستگاه از قبل ردیابی شده | قبل از تست مجدد نصب، از یک دستگاه تازه استفاده کنید یا Forget Device را در پنل انجام دهید. |
| install هنوز ثبت نشده | Event ها ذخیره میشوند اما در آمار نمایش داده نمیشوند تا زمانی که install موفق باشد. ابتدا install را تأیید کنید. |
| سطح لاگ بسیار پایین | سطح لاگ را روی Verbose تنظیم کنید و پس از یک Session، کنسول Unity و لاگهای دستگاه را بررسی کنید. |
برای مراحل Testing Console، تست یکپارچهسازی را دنبال کنید.
چطور Google Advertising ID را روی Android تأیید کنم؟
اپلیکیشن را در sandbox با verbose logging اجرا کنید. یک Session یا Event ردیابی کنید، سپس در خروجی verbose به دنبال gps_adid بگردید. اگر پیدا نشد، Google Play Services بهدرستی پیکربندی نشده: Google Play Services را در Basic Setup ببینید.
ردیابی Event
چطور Event ها را ردیابی کنم؟
توکنهای Event را در پنل ایجاد کنید، سپس از AdTraceEvent در هر جایی از منطق بازی استفاده کنید:
AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");
adtraceEvent.addCallbackParameter("key", "value");
AdTrace.trackEvent(adtraceEvent);
برای درآمد، حذف تکراری و پارامترهای Callback، ردیابی Event را ببینید.
چرا Event ها در پنل نمایش داده نمیشوند؟
install باید ابتدا روی دستگاه ثبت شود. Adtrace Event ها را قبل از install دریافت و ذخیره میکند، اما تا زمانی که install ردیابی نشود در آمار پنل نمایش داده نخواهند شد. install را در لاگهای verbose یا Testing Console تأیید کنید.
برای درآمد خرید درونبرنامهای، trackEvent را فقط پس از تکمیل خرید فراخوانی کنید و یک transactionId منحصربهفرد تنظیم کنید تا از درآمد تکراری جلوگیری شود.
عیبیابی
بدون داده یا بدون شناسه دستگاه
| علامت | راهحل |
|---|---|
| بدون install یا Session در پنل | بررسی کنید prefab در اولین scene است، توکن اپلیکیشن صحیح است، environment برای تست روی Sandbox است و پنل ترافیک sandbox را نمایش میدهد. |
gps_adid گم است (Android) | Play Services ads identifier AAR و مجوز AD_ID را اضافه کنید. با لاگهای verbose مجدداً تست کنید. |
| install در sandbox کار میکند اما در production نه | قوانین ProGuard keep را از Basic Setup اضافه کنید. |
| هشدارهای post-build در کنسول Unity | خروجی مرحله post-build AdTraceEditor.cs را مرور کنید؛ ورودیهای plugin یا manifest گمشده را رفع کنید. |
| نصبهای Huawei App Gallery | پشتیبانی OAID/Huawei referrer را مطابق مستندات Unity SDK و راهنمای native OAID اطمینان حاصل کنید. |
چکلیست کلی
- AdTrace prefab در اولین scene موجود است (یا
AdTrace.startدستی یک بار فراخوانی شده). - توکن اپلیکیشن معتبر و environment صحیح Sandbox/Production.
- verbose logging در طول توسعه فعال است.
- دستگاه تازه یا Forget Device قبل از تست مجدد install.
- پلاگینهای Android و مجوزها پیکربندی شدهاند؛ مراحل post-build iOS بدون خطا کامل شدهاند.
برای مشکلات مداوم، scene نمونه را در Assets/AdTrace/ExampleGUI/ExampleGUI.unity در پکیج مرور کنید یا با پشتیبانی Adtrace تماس بگیرید.