ردیابی Uninstall / Reinstall

از Adtrace Android SDK برای اندازه‌گیری uninstall و reinstall استفاده کنید. Adtrace silent push notification را با استفاده از push token دستگاه ارسال می‌کند، سپس بررسی می‌کند که آیا اپ شما هنوز نصب است.

مفهوم	معنی
Uninstall	دستگاه دیگر اپ شما را ندارد. Adtrace این را با یک silent push روزانه شناسایی می‌کند.
Reinstall	اپ حذف شد، سپس دوباره نصب و باز شد.
Push token	توکن FCM برای دستگاه. باید با AdTrace.setPushToken به SDK ارسال شود.
Silent push	پیام داده بدون نمایش به کاربر؛ Adtrace تقریباً روزانه یک بار ارسال می‌کند.

نکته

اندازه‌گیری uninstall و reinstall برای اپ‌هایی از هر store یا دانلود مستقیم کار می‌کند اگر دستگاه Google Play Services داشته باشد. دستگاه‌های بدون Google Play Services (مثلاً برخی دستگاه‌های Amazon یا Huawei) پشتیبانی نمی‌شوند.

قبل از شروع

نیاز	جزئیات
Adtrace Android SDK	از آخرین نسخه استفاده کنید
Firebase در اپ	Firebase را به پروژه Android خود اضافه کنید
کلید FCM HTTP v1	یک کلید JSON سرویس‌اکانت بسازید و در پنل Adtrace آپلود کنید
تنظیم پنل	تنظیمات uninstall / reinstall را برای اپ خود در پنل کامل کنید

هشدار

Firebase Cloud Messaging Legacy API ها منسوخ شده‌اند. فقط از FCM HTTP v1 استفاده کنید. یک کلید خصوصی JSON جدید ایجاد کنید؛ از یک legacy server key مجدداً استفاده نکنید. راهنمای مهاجرت به HTTP v1 Google را ببینید.

۱. اتصال Google FCM به Adtrace

Silent push از طریق Firebase Cloud Messaging (FCM) API Google به Adtrace اجازه می‌دهد uninstall و reinstall را اندازه‌گیری کند. Adtrace به یک کلید خصوصی سرویس‌اکانت FCM HTTP v1 (JSON) نیاز دارد تا FCM را فراخوانی کند.

ایجاد نقش سفارشی

1. Google Cloud Console را باز کنید.
2. پروژه Google Cloud که به پروژه Firebase شما لینک شده را انتخاب کنید.
3. به IAM & Admin → Roles بروید.
4. + Create Role را انتخاب کنید.
5. وارد کنید:
   • Title: Adtrace Uninstall
   • ID: adtrace_uninstall
   • Role launch stage: General Availability
6. + Add Permissions را انتخاب کنید.
7. به دنبال cloudmessaging.messages.create بگردید، آن را انتخاب کنید، سپس Add.
8. Create را انتخاب کنید.

ایجاد یک سرویس‌اکانت

1. در IAM & Admin، Service Accounts را باز کنید.
2. + Create Service Account را انتخاب کنید.
3. نام سرویس‌اکانت: Adtrace Uninstall Service Account.
4. Create and Continue را انتخاب کنید.
5. در Select a role، به دنبال Adtrace Uninstall بگردید و آن نقش را انتخاب کنید.
6. Continue، سپس Done را انتخاب کنید.

ایجاد و دانلود کلید خصوصی

1. سرویس‌اکانت جدید را باز کنید (ایمیل شبیه adtrace-uninstall-service-account@project-id.iam.gserviceaccount.com به نظر می‌رسد).
2. تب Keys را باز کنید.
3. Add Key → Create new key را انتخاب کنید.
4. JSON را انتخاب کنید، سپس Create.

فایل JSON به دستگاه شما دانلود می‌شود. آن فایل را در پنل Adtrace برای اتصال FCM / uninstall اپ خود آپلود کنید.

نمونه شکل JSON دانلود شده (مقادیر placeholder هستند):

{
  "type": "service_account",
  "project_id": "app_name",
  "private_key_id": "some_private_key",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "adtrace-uninstall-service-acco@app_name.iam.gserviceaccount.com",
  "client_id": "6152715792181423123124",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/adtrace-uninstall-service-acco%40app_name.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

۲. اضافه کردن Firebase Messaging به اپ

اگر هنوز ندارید، وابستگی Firebase Messaging را اضافه کنید:

Kotlin (build.gradle.kts)

dependencies {
    // از نسخه firebase-messaging فعلی یا Firebase BoM استفاده کنید
    implementation("com.google.firebase:firebase-messaging:23.4.0")
}

Groovy (build.gradle)

dependencies {
    // از نسخه firebase-messaging فعلی یا Firebase BoM استفاده کنید
    implementation 'com.google.firebase:firebase-messaging:23.4.0'
}

یک FCM client تنظیم کنید: راهنمای تنظیم FCM Android Google را دنبال کنید.

Firebase را قبل از فراخوانی AdTrace.onCreate() مقداردهی اولیه کنید. به مثال‌ها مراجعه کنید.

۳. ارسال push token به SDK

Push token ها برای ردیابی uninstall و reinstall الزامی هستند. پس از دریافت توکن FCM (و هر زمان که تغییر می‌کند)، آن را به Adtrace پاس دهید.

Method signature

public static void setPushToken(String token, Context context)

پارامتر	نوع	توضیح
token	String	توکن push notification FCM برای دستگاه
context	Context	Context اندروید. getApplicationContext() / applicationContext را ترجیح دهید

Overload توصیه شده

AdTrace.setPushToken(token, context) را ترجیح دهید. آرگومان context موارد بیشتری را پوشش می‌دهد تا توکن به طور مطمئن ارسال شود.

مثال native SDK

Java

AdTrace.setPushToken(pushNotificationsToken, getApplicationContext());

Kotlin

AdTrace.setPushToken(pushNotificationsToken, applicationContext)

WebBridge / WebView SDK

AdTrace.setPushToken(pushNotificationsToken);

۴. مدیریت silent push notification ها

Adtrace تقریباً هر روز یک silent push برای بررسی وضعیت نصب می‌فرستد. اگر اپ شما هم push ارسال می‌کند، onMessageReceived را در FirebaseMessagingService override کنید تا پیام‌های silent Adtrace مثل notification عادی به کاربر نشان داده نشوند.

Adtrace برای تشخیص payload های silent push یک کمک‌تابع فراهم می‌کند:

Util.isAdTraceUninstallDetectionPayload(payload)

یا از یک بررسی ساده استفاده کنید:

if (remoteMessage.getData().get("title") == null
        && remoteMessage.getData().get("body") == null) {
    // Silent push از Adtrace - مدیریت UI نیاز ندارد
}

برای مثال کامل FirebaseMessagingService (تجدید توکن + Util.isAdTraceUninstallDetectionPayload اختیاری)، به مثال‌ها مراجعه کنید.

۵. آماده برای اندازه‌گیری

پس از اینکه:

1. کلید JSON FCM HTTP v1 را در پنل آپلود کردید
2. Firebase و Adtrace SDK را مقداردهی اولیه کردید
3. هر زمان که توکن در دسترس است یا تغییر می‌کند AdTrace.setPushToken را فراخوانی کردید
4. Silent push ها را به درستی مدیریت کردید

...اندازه‌گیری uninstall و reinstall به صورت خودکار اجرا می‌شود.

بعدی: مثال‌ها · آزمایش یکپارچه‌سازی