FAQ
سوالات رایج درباره یکپارچهسازی و استفاده از Adtrace Android SDK، از وابستگیها و آزمایش گرفته تا رویدادها، deep link ها، ردیابی uninstall، و WebBridge.
یکپارچهسازی و وابستگیها
مدام "package not resolved" میبینم
| بررسی | اقدام |
|---|---|
| مختصات Artifact | Maven Central را برای io.adtrace جستجو کنید و group ID، artifact ID، و نسخه را تأیید کنید. |
| Gradle sync | پس از تغییر وابستگیها، پروژه را sync کنید و rebuild کنید. |
| شبکه / VPN | در برخی مناطق برای دسترسی به Maven Central نیاز به VPN است. |
به دریافت Adtrace SDK مراجعه کنید.
کدام نسخه SDK را باید استفاده کنم؟
در صورت امکان از آخرین نسخه stable استفاده کنید. نسخههای قدیمیتر ممکن است هنوز کار کنند، اما پشتیبانی و رفع خطاها بر نسخههای فعلی متمرکز است. برای یادداشتهای نسخه به صفحه releases Android SDK مراجعه کنید.
اگر از نسخه منسوخ شده استفاده کنم چه اتفاقی میافتد؟
یک SDK منسوخ شده ممکن است برای ویژگیهایی که امروز استفاده میکنید کار کند، اما Adtrace نسخه های قدیمی را به طور کامل پشتیبانی نمیکند. قبل از نسخه بعدی خود ارتقا را برنامهریزی کنید. اگر نیاز به راهنمایی دارید با پشتیبانی Adtrace تماس بگیرید.
نمیخواهم از Maven Central استفاده کنم
میتوانید SDK را از فایلهای aar یا jar منتشر شده با هر نسخه یکپارچه کنید. رفتار مشابه وابستگی Maven است. Build ها را از صفحه releases دانلود کنید.
اگر Google Play Services اضافه نکنم چه اتفاقی میافتد؟
SDK بدون throw کردن exception اجرا میشود، اما advertising ID و ویژگیهای مرتبط کار نخواهند کرد. برای عملکرد کامل Google Play Services را اضافه کنید. به اضافه کردن Google Play Services مراجعه کنید.
اگر Install Referrer اضافه نکنم چه اتفاقی میافتد؟
SDK بدون throw کردن exception اجرا میشود، اما attribution کمپین store از install referrer محدود خواهد بود. برای attribution کامل کتابخانه Install Referrer را اضافه کنید. به اضافه کردن Install Referrer مراجعه کنید.
آیا میتوانم AdTraceReceiver را از AndroidManifest.xml حذف کنم؟
Google روش تحویل install broadcast را به عنوان روش بلندمدت منسوخ کرده (مارس ۲۰۲۰)، اما اگر به broadcast INSTALL_REFERRER وابسته هستید همچنان به یک receiver نیاز دارید.
| تنظیم شما | اقدام |
|---|---|
بدون receiver سفارشی INSTALL_REFERRER | AdTraceReceiver را درون تگ <application> نگه دارید. |
| قبلاً receiver خودتان را دارید | از چندین broadcast receiver پیروی کنید تا Adtrace همچنان referrer را دریافت کند. |
Google Play به دلیل مجوز AD_ID آپدیت من را رد کرد
Google Play سیاستهای Families را بر اساس مخاطبان هدف شما اعمال میکند.
| مخاطب | اقدام |
|---|---|
| اپهای صرفاً برای کودکان (API 33+) | AD_ID را درخواست نکنید. مجوز را حذف کنید و گزینه Kids Google Play را فعال کنید. |
| اپهای نه صرفاً برای کودکان | مجوز را نگه دارید و اعلام کنید که فقط کودکان را هدف قرار نمیدهید. |
آیا میتوانم در حالت Environment.SANDBOX داده را در پنل ببینم؟
بله. SDK در هر دو حالت production و sandbox داده ارسال میکند. Sandbox به شما امکان میدهد ترافیک آزمایشی را از کاربران واقعی در پنل جدا کنید. همیشه قبل از انتشار به AdTraceConfig.ENVIRONMENT_PRODUCTION سوئیچ کنید.
من قبلاً یک کلاس دارم که Application را extend میکند. آیا به کلاس دیگری نیاز دارم؟
خیر. مقداردهی اولیه Adtrace را به زیر کلاس Application موجود خود اضافه کنید. SDK باید از طریق AdTrace.onCreate، AdTrace.onResume، و AdTrace.onPause به شروع اپ و انتقالات به پسزمینه hook شود. به مقداردهی اولیه Adtrace SDK مراجعه کنید.
حداقل نیاز برای کارکرد Adtrace چیست؟
با وابستگیهای الزامی در جای خود، باید:
- یک
AdTraceConfigباcontext،appToken، وenvironmentبسازید. AdTrace.onCreate(config)را فراخوانی کنید.AdTrace.onResume()وAdTrace.onPause()را در Callback های lifecycle صحیح فراخوانی کنید.
پس از آن، SDK به طور خودکار Install و Session را ارسال میکند. به پیکربندی ردیابی Session مراجعه کنید.
آیا فراخوانی AdTrace.onCreate برای ارسال Install کافی است؟
خیر. onCreate تنها پیکربندی را اعمال میکند. AdTrace.onResume() را برای شروع SDK و trigger کردن منطق install و Session فراخوانی کنید.
آزمایش
چگونه Adtrace را برای آزمایش پیکربندی کنم؟
AdTraceConfig.ENVIRONMENT_SANDBOXرا تنظیم کنید (قبل از انتشار به production سوئیچ کنید).- سطح لاگ را به verbose تنظیم کنید. به سطح لاگ مراجعه کنید.
- در یک دستگاه تازه با دستگاه متصل به Logcat نصب کنید.
برای مراحل Testing Console از آزمایش یکپارچهسازی پیروی کنید.
«دستگاه تازه» چیست؟
پس از اولین باز کردن، SDK حالت را در دستگاه ذخیره میکند. برای تأیید یک Install جدید، از دستگاهی استفاده کنید که هرگز اپ شما را با Adtrace اجرا نکرده، یا دستگاه را فراموش کنید و داده اپ را پاک کنید.
چگونه یک دستگاه را فراموش کنم؟
- پنل Adtrace را باز کنید.
- به Settings → Testing Console بروید.
- شناسه دستگاه خود را وارد کنید.
- روی Forget Device کلیک کنید.
چگونه شناسه دستگاه خود را بدست آورم؟
| شناسه | توضیح | نحوه دریافت |
|---|---|---|
| Google Advertising ID | UUID از Google Play services (gps_adid) | Logcat پس از لاگ verbose، یا API های شناسههای دستگاه |
شناسه دستگاه Adtrace (adid) | ID اختصاص داده شده توسط Adtrace | Logcat یا مستندات شناسههای دستگاه |
با sandbox و لاگ verbose فعال، در Logcat به دنبال gps_adid و adid بگردید:
gps_adid: 7c67ef26-830e-49b7-8948-b868b19bf4b3
"adid" : "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"
رویدادها و درآمد
eventToken چیست؟
eventToken شناسه رشتهای برای یک رویداد است که در پنل Adtrace ایجاد میکنید. خارج از پروژه شما معنایی ندارد؛ هنگام ساخت AdTraceEvent در کد از آن استفاده کنید. به ردیابی رویداد مراجعه کنید.
رویداد منحصربهفرد چیست؟
یک رویداد منحصربهفرد یک بار در طول عمر اپ ضبط میشود (مثلاً ثبتنام حساب). هنگام ایجاد رویداد آن را در پنل فعال کنید. هیچ کد SDK اضافی لازم نیست.
چه تعداد رویداد میتوانم در یک دوره زمانی ارسال کنم؟
هیچ محدودیتی وجود ندارد. میتوانید هر تعداد رویداد با هر فاصله زمانی ارسال کنید.
چه تعداد رویداد مختلف میتوانم تعریف کنم؟
هیچ محدودیت سختی در پنل وجود ندارد، اما تعداد زیادی نام رویداد مجزا تحلیل را سختتر میکند. یک مجموعه کوچک از رویدادهای قابل استفاده مجدد با پارامترهای value ترجیح دهید.
به ردیابی رویدادها مراجعه کنید.
چگونه بدانم یک رویداد با موفقیت ارسال شد؟
یک Callback Success callbacks / Failure callbacks رویداد ثبت کنید. به ارسال اطلاعات Callback مراجعه کنید.
آیا Adtrace درآمد را بر اساس ارز تبدیل میکند؟
خیر. کد ارز درآمد را برچسبگذاری میکند تا مقادیر در گزارشها مخلوط نشوند. برای تحلیل یکپارچه، درآمد را در یک ارز ارسال کنید (مثلاً USD، IRR، یا واحد محلی شما).
درآمد را از طریق پارامترهای value رویداد ارسال نکنید. از API درآمد اختصاصی در شیء رویداد استفاده کنید.
چرا حذف تکراری درآمد مهم است و چگونه از آن استفاده کنم؟
ضربه دوبار یا شبکههای کند میتوانند همان رویداد خرید را چند بار fire کنند.
یک order ID منحصربهفرد هنگام ردیابی درآمد پاس دهید. اگر همان order ID دوباره ارسال شود، Adtrace آن را حذف تکر اری میکند. به حذف تکراری درآمد مراجعه کنید.
چگونه میتوانم داده سفارشی به یک رویداد اضافه کنم؟
از پارامترهای Callback (رشتههای key/value) در رویداد استفاده کنید. به پارامترهای value رویداد مراجعه کنید.
چه تعداد پارامتر میتوانم به یک رویداد اضافه کنم؟
هیچ محدودیت ثابتی وجود ندارد. از یک schema key یکپارچه در رویدادها استفاده کنید تا داده تمیز بماند.
Session ها
چگونه باید یک Session ارسال کنم؟
پس از پیکربندی Session Tracking در lifecycle مربوط به Activity، SDK بهطور خودکار Sessionها را ارسال میکند. هیچ فراخوانی API Session دستی لازم نیست.
چگونه بدانم یک Session با موفقیت ارسال شد؟
از Success callbacks و Failure callbacks مربوط به Session استفاده کنید. به ارسال اطلاعات Callback مراجعه کنید.
Deep linking
چگونه یک deeplink برای Adtrace تعریف کنم؟
Deeplink ها Android app link ها یا intent filter ها هستند که تعریف میکنید. Adtrace پارامترهای deeplink را از طریق URL های tracker بدون تغییر آنها پاس میدهد. به Deep linking مراجعه کنید.
Deferred deeplink چیست؟
یک deferred deeplink زمانی اعمال میشود که کاربر روی یک لینک قبل از نصب اپ کلیک کند. پس از نصب و اولین باز کردن، SDK URL معوق را به اپ شما تحویل میدهد. به Deferred deeplink مراجعه کنید.
آیا برای deferred deeplinking به نوع deeplink متفاوتی نیاز دارم؟
خیر. از همان فرمت deeplink استفاده کنید. tracker را به درستی در پنل پیکربندی کنید.
Uninstall و Reinstall
برای ردیابی uninstall چه نیازی است؟
Firebase Cloud Messaging را پیادهسازی کنید و توکن FCM را با AdTrace.setPushToken ارسال کنید. Adtrace از silent push برای شناسایی uninstall ها استفاده میکند. به ردیابی Uninstall و Reinstall مراجعه کنید.
Silent push چیست؟
Silent push یک پیام FCM فقط داده بدون عنوان یا متن قابل مشاهده است. Adtrace روزانه حدود یک بار ارسال میکند تا بررسی کند اپ شما هنوز نصب است. به مثالهای پیادهسازی مراجعه کنید.
چرا اپ من notification های خالی نشان میدهد؟
پیامهای silent push را فیلتر نمیکنید. پیامهایی با title و body خالی را بدون نمایش notification مدیریت کنید. به مثالهای پیادهسازی uninstall مراجعه کنید.
آیا uninstall یک رویداد است؟ آیا فوراً در پنل ظاهر میشود؟
خیر. Uninstall یک رویداد SDK مانند خرید یا login نیست. از طریق silent push و validation توکن FCM شناسایی میشود.
داده پنل real-time نیست. بهروزرسانیها اغلب تا ۲۴ ساعت یا بیشتر طول میکشند.
کجا فایل Firebase JSON برای پنل را بدست آورم؟
فایل یک دانلود از Firebase console نیست. یک کلید خصوصی سرویساکانت Google Cloud (JSON) برای FCM HTTP v1 است:
- پروژه Google Cloud لینک شده به اپ Firebase خود را باز کنید.
- یک نقش IAM سفارشی، سرویساکانت، و کلید JSON ایجاد کنید. گام به گام: تنظیم ردیابی uninstall.
- JSON را در پنل Adtrace برای اتصال FCM اپ خود آپلود کنید.
SDK Signature
آیا فیلد "App Version" پنل باید با نسخه اپ من مطابقت داشته باشد؟
خیر. App Version در SDK Signature نسخه signature است، نه versionName یا versionCode Android شما. یک نسخه signature میتواند چندین نسخه اپ را پوشش دهد.
Secret ID (Security ID) چیست؟
Secret ID شناسهای است که Adtrace هنگام ایجاد signature در پنل اختصاص میدهد. آن را به عنوان اولین آرگومان به setAppSecret(secretId, info1, info2, info3, info4) پاس دهید. به SDK signature مراجعه کنید.
آیا میتوانم signature ها را قبل از انتشار آزمایش کنم؟
بله.
- Signature های آزمایشی (یا production) را در پنل ایجاد کنید.
- یک APK/AAB قابل نصب برای هر signature با مقادیر مطابق
setAppSecretبسازید. - هر build را روی یک دستگاه آزمایشی به صورت نصب تازه نصب کنید.
- رویدادهای آزمایشی ارسال کنید و Show by SDK Signature را در Statistics فعال کنید.
اگر Fraud Detection فعال باشد اما یک APK بدون signature باشد چه اتفاقی میافتد؟
نصبهایی از APK بدون signature مورد انتظار میتوانند به عنوان تقلب علامتگذاری شوند. Fraud Detection را تنها زمانی فعال کنید که هر APK ارسال شده برای آن کانال مقادیر setAppSecret صحیح را داشته باشد.
WebBridge
اپ من یک activity با WebView است. Adtrace چگونه کار میکند؟
WebBridge Adtrace Android SDK native را به JavaScript در WebView شما متصل میکند.
| نقطه ورود اپ | مقداردهی اولیه از |
|---|---|
| کاربر ابتدا روی محتوای web میرسد | سمت Web. به WebBridge (WebView) مراجعه کنید. |
| کاربر از UI native شروع میکند، سپس WebView را باز میکند | ابتدا سمت Native (Case B)، سپس bridge به web. به WebBridge (WebView) مراجعه کنید. |
آیا میتوانم AdTrace.onCreate را هم از native و هم از JavaScript فراخوانی کنم؟
خیر. تنها یک نمونه SDK برای هر پردازش وجود دارد. یک بار مقداردهی اولیه کنید:
- Case A (فقط WebBridge):
AdTrace.onCreateرا تنها از JavaScript فراخوانی کنید - Case B (ترکیبی):
AdTrace.onCreateرا تنها از native فراخوانی کنید؛ JS ازtrackEventبدونonCreateاستفاده میکند
فراخوانی هر دو AdTrace already initialized را لاگ میکند. به WebBridge (WebView) مراجعه کنید.
آیا WebBridge میتواند با SDK native مطابقت داشته باشد؟
بله. هر API native مستند شده برای Android معادل WebBridge دارد.
آیا میتوانم از Adtrace برای PWA استفاده کنم؟
برای یک Progressive Web App مستقل در مرورگر، از Adtrace Web SDK استفاده کنید. اگر PWA داخل یک Android WebView اجرا میشود، از Android SDK به اضافه WebBridge استفاده کنید.
آیا میتوانم از Adtrace برای TWA استفاده کنم؟
بله. Trusted Web Activity پشتیبانی میشود. به مستندات TWA مراجعه کنید.
آیا نیاز دارم اسکریپتهای SDK را در سمت web اضافه کنم؟
بله. فایلهای asset WebBridge را import کنید تا web و native ساختار داده یکسان داشته باشند. به فایلهای WebBridge JS مراجعه کنید.
آیا میتوانم WebBridge و Web SDK را در یک پروژه استفاده کنم؟
بله، با جداسازی:
| Context | SDK |
|---|---|
| صفحه بارگذاری شده داخل WebView اپ | فایلهای asset WebBridge |
| ص فحه بارگذاری شده در مرورگر موبایل | Web SDK |
نمونه پروژههای WebBridge کجاست؟
| پروژه | لینک |
|---|---|
| نمونه Android WebBridge | example-app-webbridge |
| سمت Web (Next.js) | nextjs-webview |
| سمت Web (Next.js 2) | nextjs-example |
شناسههای دستگاه و attribution
چگونه داده attribution را دریافت کنم؟
یک attribution listener تنظیم کنید. SDK آن را هنگام دریافت یا بهروزر سانی attribution فراخوانی میکند. به Attribution کاربر مراجعه کنید.
Attribution چه مدت طول میکشد؟
هیچ زمان ثابتی وجود ندارد. به سرعت شبکه و بار سرور بستگی دارد، اما معمولاً در چند ثانیه انجام میشود. منطق خود را در Callback attribution پیادهسازی کنید نه polling.
GPS AdId / Google Advertising ID / Google Play Services Ad ID چیست؟
advertising ID یک ID منحصربهفرد، قابل بازنشانی توسط کاربر برای تبلیغات از Google Play services است. به مستندات Google مراجعه کنید.
چگونه Google Advertising ID را بدست آورم؟
Adtrace SDK آن را به صورت async میخواند. منطق اپ را در انتظار Callback مسدود نکنید. به شناسههای دستگاه مراجعه کنید.
مدام 00000000-0000-0000-0000-000000000000 یا null برای advertising ID میگیرم
| دلیل | توضیحات |
|---|---|
| کاربر بازنشانی کرده یا انصراف داده | کاربر ممکن است دسترسی ad ID را حذف یا محدود کرده باشد. |
مجوز AD_ID مفقود (Android 13+) | <uses-permission android:name="com.google.android.gms.permission.AD_ID"/> را در manifest اعلام کنید. |
| شبیهساز بدون Google Play | از یک دستگاه فیزیکی یا تصویر شبیهساز با Google Play استفاده کنید. |
آیا مجوز runtime برای AD_ID وجود دارد؟
خیر. مجوز را تنها در manifest اعلام کنید.
برخی دستگاهها Google Ad ID پشتیبانی نمیکنند (مثلاً Huawei)
Adtrace دستگاههایی که به جای Google Ad ID از OAID استفاده میکنند را پشتیبانی میکند. OAID plugin را به پروژه خود اضافه کنید. به Huawei و OAID مراجعه کنید.
رفع مشکل
خطای "Session failed (Ignoring too frequent session.)" میبینم
این معمولاً در حین آزمایش نصب اتفاق میافتد. حذف و نصب مجدد کافی نیست تا یک نصب جدید trigger شود - سرورهای Adtrace همچنان حالت Session قبلی آن دستگاه را نگه میدارند.
- مقادیر
app_tokenوgps_adidرا در لاگ خطا پیدا کنید. - Testing Console را در پنل Adtrace باز کنید و از Forget Device استفاده کنید.
- اپ را حذف نصب کنید، داده اپ را پاک کنید، سپس دوباره نصب و باز کنید.
"Install tracked" را در لاگها نمیبینم
صرفاً اجرای مجدد اپ از Android Studio فایلهای state محلی SDK را پاک نمیکند. SDK آن فایلها را در هنگام راهاندازی مجدد میبیند و آن را به عنوان Session، نه نصب جدید تلقی میکند.
برای شبیهسازی نصب تازه:
- اپ را به طور کامل از دستگاه حذف نصب کنید.
- دستگاه را فراموش کنید در Testing Console.
- از Android Studio مجدداً نصب کنید. سپس باید
Install trackedرا در Logcat ببینید.
آیا broadcast receiver من install referrer را capture میکند؟
broadcast receiver را به صورت دستی با adb آزمایش کنید:
adb shell am broadcast \
-a com.android.vending.INSTALL_REFERRER \
-n com.your.appname/io.adtrace.sdk.AdTraceReferrerReceiver \
--es "referrer" "adtrace_reftag%3Dadt1ex4%26utm_source%3Dnetwork"
com.your.appname را با package ID اپ خود جایگزین کنید. با لاگ verbose فعال باید یک لاگ مانند این ببینید:
V/AdTrace: Referrer to parse (adtrace_reftag=adt1ex...) from reftag
از & بدون encoding در دستورات adb استفاده نکنید - adb referrer را در اولین & قطع میکند. کل مقدار referrer را URL-encode کنید.
آیا میتوانم یک رویداد را در راهاندازی اپ trigger کنم؟
ردیابی رویدادها داخل Application.onCreate شما تعداد نصب و Session نادرستی تولید میکند. Application.onCreate هم توسط OS و هم رویدادهای سیستمی فراخوانی میشود، نه تنها توسط راهاندازیهای اپ توسط کاربر.
| هدف | رویکرد توصیه شده |
|---|---|
| ردیابی چیزی پس از نصب | از Callback attribution استفاده کنید |
| ردیابی چیزی هنگام باز کردن اپ توسط کاربر | فراخوانی را در Activity.onCreate برای activity مربوطه قرار دهید |
SDK مقداردهی اولیه شده اما رویدادها dropped میشوند
فراخوانی متدهای SDK قبل از کامل شدن AdTrace.onCreate باعث میشود اقدامات به آرامی نادیده گرفته یا dropped شوند:
| اقدام قبل از init | نتیجه |
|---|---|
trackEvent | رویداد به طور دائمی dropped میشود |
setEnabled(false) | Toggle نادیده گرفته میشود |
setOfflineMode(true) | در هنگام راهاندازی تأثیری ندارد |
SDK را تا حد ممکن زود در Application.onCreate مقداردهی اولیه کنید، سپس هر اقدام معوق را برای اجرا پس از بازگشت AdTrace.onCreate صف کنید.
ردیابی Session و اعداد DAU اشتباه به نظر میرسند
اگر SDK دیر مقداردهی اولیه شود - مثلاً تنها زمانی که کاربر به یک صفحه خاص ناوبری میکند نه در شروع اپ - اعداد DAU میتوانند اشتباه باشند.
تنظیم: در Application.onCreate (یا اولین Callback lifecycle ممکن) مقداردهی اولیه کنید، نه در یک activity.