شروع کار با SDK اندروید ادتریس

این راهنما مراحل اولیه پیاده‌سازی SDK اندروید ادتریس را پوشش می‌دهد: نصب SDK، پیکربندی پروژه، مقداردهی اولیه، راه‌اندازی Session Tracking و تأیید صحت یکپارچه‌سازی. در پایان، اپلیکیشن شما آماده ردیابی Install، Session و Event خواهد بود.

نوع یکپارچه‌سازی خود را انتخاب کنید

این صفحه مخصوص اپلیکیشن‌های Native Android نوشته‌شده با Java یا Kotlin است.

اگر از TWA (Trusted Web Activity) یا WebBridge (WebView) استفاده می‌کنید، از مرور SDK اندروید مسیر مناسب را انتخاب کنید.

۱. دریافت SDK ادتریس

SDK را با یکی از روش‌های زیر به پروژه اضافه کنید:

• Maven (پیشنهادی): وابستگی را به فایل build.gradle ماژول اپ اضافه کنید. جدیدترین نسخه‌ها در Maven Central منتشر می‌شوند.
• JAR / AAR: فایل SDK را از صفحه Releases در GitHub دانلود و دستی وارد پروژه کنید.

حداقل نسخه پشتیبانی‌شده

SDK ادتریس حداقل به API Level 9 (Android Gingerbread) نیاز دارد.

این راهنما فرض می‌کند از Android Studio استفاده می‌کنید.

• اگر اپ شما دارای Android WebView است، پس از تکمیل مراحل Native، راهنمای WebBridge (WebView) را نیز دنبال کنید. اگر ردیابی فقط از طریق JavaScript انجام می‌شود، از Case A استفاده کنید.
• برای اپ‌های Google Play Store، افزودن Install Referrer را فراموش نکنید.

Maven

وابستگی کتابخانه ادتریس را در بخش dependencies فایل build.gradle ماژول اپلیکیشن اضافه کنید:

build.gradle

dependencies {
    implementation 'io.adtrace:android-sdk:2.6.0'
}

۲. افزودن Google Play Services

وابستگی play-services-ads-identifier را به پروژه اضافه کنید تا SDK بتواند Google Advertising ID (gps_adid) را دریافت کند. این شناسه برای شناسایی دستگاه در اتریبیوشن استفاده می‌شود:

build.gradle

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}

۳. افزودن Install Referrer

اپ‌هایی که در Google Play Store منتشر می‌شوند باید از Google Play Referrer API استفاده کنند تا ادتریس بتواند منشأ نصب را به‌درستی شناسایی و اتریبیوشن را انجام دهد.

کتابخانه Install Referrer را به پروژه اضافه کنید:

build.gradle

dependencies {
    implementation 'com.android.installreferrer:installreferrer:2.2'
}

اگر از ProGuard یا R8 استفاده می‌کنید، مطمئن شوید کلاس‌های Install Referrer در فرآیند بهینه‌سازی حذف نمی‌شوند. Rule موردنیاز از قبل در بخش پیکربندی ProGuard قرار داده شده است.

۴. افزودن Permissionها

Permissionهای لازم برای SDK ادتریس را در فایل AndroidManifest.xml تعریف کنید.

Permissionهای موردنیاز

برای اینکه SDK بتواند به شبکه دسترسی داشته باشد، Permissionهای زیر را اضافه کنید:

AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

اپ‌هایی که در Google Play منتشر نمی‌شوند

این Permission را نیز اضافه کنید تا SDK بتواند وضعیت شبکه Wi-Fi را بخواند:

AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Google Advertising ID (AD_ID)

اگر اپ شما Android 12 (API Level 31) یا بالاتر را هدف قرار می‌دهد و در Google Play Store منتشر می‌شود، این Permission را اضافه کنید تا SDK بتواند Advertising ID را بخواند:

AndroidManifest.xml

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

اگر اپ شما برای کودکان (COPPA / Play Store Kids) است یا نباید Advertising ID را بخواند، این Permission را حذف کنید:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>
</manifest>

برای تنظیمات کامل اپلیکیشن‌های کودکان، به راهنمای اپ‌های کودکان مراجعه کنید.

۵. پیکربندی ProGuard

اگر برای بهینه‌سازی اپ از ProGuard یا R8 استفاده می‌کنید، Ruleهای زیر را به فایل proguard-rules.pro اضافه کنید تا کلاس‌های موردنیاز SDK حذف نشوند:

proguard-rules.pro

-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 Play منتشر نمی‌شوند

این Rule را نیز اضافه کنید:

proguard-rules.pro

-keep public class io.adtrace.sdk.** { *; }

۶. مقداردهی اولیه SDK ادتریس

این بخش مخصوص اپ‌های Native (Java / Kotlin) است.

• برای اپ‌هایی با WebView، پس از این مرحله WebBridge (WebView) را نیز دنبال کنید.
• برای Trusted Web Activity، مستندات TWA را مطالعه کنید.

برای مقداردهی اولیه SDK به دو مقدار نیاز دارید:

• appToken: توکن اپلیکیشن را از پنل ادتریس دریافت کنید.
• environment: در زمان تست از AdTraceConfig.ENVIRONMENT_SANDBOX و برای انتشار از AdTraceConfig.ENVIRONMENT_PRODUCTION استفاده کنید. ادتریس با این مقدار، ترافیک تستی را از کاربران واقعی جدا می‌کند. هنگام اجرای مجدد تست، environment را دوباره روی Sandbox بگذارید. ادتریس با این مقدار، ترافیک تستی را از کاربران واقعی جدا می‌کند. هنگام اجرای مجدد تست، environment را دوباره روی Sandbox بگذارید.

SDK را در یک کلاس سراسری Application مقداردهی کنید. اگر هنوز این کلاس را ندارید:

1. یک کلاس جدید بسازید که از Application ارث‌بری کند.
2. فایل AndroidManifest.xml را باز کنید و در تگ <application> مقدار android:name را تنظیم کنید. مثلاً برای کلاسی به نام GlobalApplication:

AndroidManifest.xml

<application
    android:name=".GlobalApplication">
    <!-- ... -->
</application>

3. مقداردهی اولیه SDK را در متد onCreate کلاس Application خود انجام دهید:

Java

GlobalApplication.java

import android.app.Application;
import io.adtrace.sdk.AdTrace;
import io.adtrace.sdk.AdTraceConfig;

public class GlobalApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        String appToken = "{YourAppToken}";
        String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;
        AdTraceConfig config = new AdTraceConfig(this, appToken, environment);
        AdTrace.onCreate(config);
    }
}

Kotlin

GlobalApplication.kt

import android.app.Application
import io.adtrace.sdk.AdTrace
import io.adtrace.sdk.AdTraceConfig

class GlobalApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        val appToken = "{YourAppToken}"
        val environment = AdTraceConfig.ENVIRONMENT_SANDBOX
        val config = AdTraceConfig(this, appToken, environment)
        AdTrace.onCreate(config)
    }
}

مقدار {YourAppToken} را با App Token اپلیکیشن خود از پنل ادتریس جایگزین کنید.

4. مقدار environment را بر اساس مرحله توسعه انتخاب کنید:

Java

// در زمان تست
String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;

// قبل از انتشار
String environment = AdTraceConfig.ENVIRONMENT_PRODUCTION;

Kotlin

// در زمان تست
val environment = AdTraceConfig.ENVIRONMENT_SANDBOX

// قبل از انتشار
val environment = AdTraceConfig.ENVIRONMENT_PRODUCTION

توجه

مقداردهی اولیه به‌تنهایی کافی نیست. برای ثبت صحیح Sessionها، پیکربندی Session Tracking را نیز انجام دهید.

۷. پیکربندی Session Tracking

Session Tracking به SDK ادتریس اطلاع می‌دهد که اپلیکیشن چه زمانی فعال یا متوقف می‌شود تا داده‌های Session با دقت به سرور ارسال شود. این مرحله الزامی است و بدون آن SDK به‌درستی کار نمی‌کند.

نحوه پیاده‌سازی به مقدار minSdkVersion اپلیکیشن بستگی دارد.

API Level 14 و بالاتر (پیشنهادی)

این روش را به همان کلاس GlobalApplication از مرحله ۶ اضافه کنید:

1. اگر قبلاً AdTrace.onResume() یا AdTrace.onPause() را در Activityهای جداگانه فراخوانی کرده‌اید، آن‌ها را حذف کنید.
2. بعد از AdTrace.onCreate(config) در Application.onCreate، یک ActivityLifecycleCallbacks ثبت کنید.
3. در onActivityResumed متد AdTrace.onResume() و در onActivityPaused متد AdTrace.onPause() را فراخوانی کنید.

این خط را بلافاصله بعد از AdTrace.onCreate(config) اضافه کنید:

Java

registerActivityLifecycleCallbacks(new AdTraceLifecycleCallbacks());

Kotlin

registerActivityLifecycleCallbacks(AdTraceLifecycleCallbacks())

این کلاس را داخل کلاس Application خود قرار دهید:

Java

private static final class AdTraceLifecycleCallbacks implements Application.ActivityLifecycleCallbacks {
    @Override
    public void onActivityResumed(Activity activity) {
        AdTrace.onResume();
    }

    @Override
    public void onActivityPaused(Activity activity) {
        AdTrace.onPause();
    }

    @Override
    public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}

    @Override
    public void onActivityStarted(Activity activity) {}

    @Override
    public void onActivityStopped(Activity activity) {}

    @Override
    public void onActivitySaveInstanceState(Activity activity, Bundle outState) {}

    @Override
    public void onActivityDestroyed(Activity activity) {}
}

Kotlin

private class AdTraceLifecycleCallbacks : Application.ActivityLifecycleCallbacks {
    override fun onActivityResumed(activity: Activity) {
        AdTrace.onResume()
    }

    override fun onActivityPaused(activity: Activity) {
        AdTrace.onPause()
    }

    override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
    override fun onActivityStarted(activity: Activity) {}
    override fun onActivityStopped(activity: Activity) {}
    override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
    override fun onActivityDestroyed(activity: Activity) {}
}

کلاس کامل Application (مقداردهی اولیه + Session Tracking)

از نمونه زیر به‌عنوان نسخه نهایی کلاس GlobalApplication برای API Level 14 و بالاتر استفاده کنید:

Java

GlobalApplication.java

import android.app.Activity;
import android.app.Application;
import android.os.Bundle;
import io.adtrace.sdk.AdTrace;
import io.adtrace.sdk.AdTraceConfig;

public class GlobalApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        String appToken = "{YourAppToken}";
        String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;
        AdTraceConfig config = new AdTraceConfig(this, appToken, environment);
        AdTrace.onCreate(config);

        registerActivityLifecycleCallbacks(new AdTraceLifecycleCallbacks());
    }

    private static final class AdTraceLifecycleCallbacks implements ActivityLifecycleCallbacks {
        @Override
        public void onActivityResumed(Activity activity) {
            AdTrace.onResume();
        }

        @Override
        public void onActivityPaused(Activity activity) {
            AdTrace.onPause();
        }

        @Override
        public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}

        @Override
        public void onActivityStarted(Activity activity) {}

        @Override
        public void onActivityStopped(Activity activity) {}

        @Override
        public void onActivitySaveInstanceState(Activity activity, Bundle outState) {}

        @Override
        public void onActivityDestroyed(Activity activity) {}
    }
}

Kotlin

GlobalApplication.kt

import android.app.Activity
import android.app.Application
import android.os.Bundle
import io.adtrace.sdk.AdTrace
import io.adtrace.sdk.AdTraceConfig

class GlobalApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        val appToken = "{YourAppToken}"
        val environment = AdTraceConfig.ENVIRONMENT_SANDBOX
        val config = AdTraceConfig(this, appToken, environment)
        AdTrace.onCreate(config)

        registerActivityLifecycleCallbacks(AdTraceLifecycleCallbacks())
    }

    private class AdTraceLifecycleCallbacks : ActivityLifecycleCallbacks {
        override fun onActivityResumed(activity: Activity) {
            AdTrace.onResume()
        }

        override fun onActivityPaused(activity: Activity) {
            AdTrace.onPause()
        }

        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
        override fun onActivityStarted(activity: Activity) {}
        override fun onActivityStopped(activity: Activity) {}
        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
        override fun onActivityDestroyed(activity: Activity) {}
    }
}

API Level 9 تا 13 (اختیاری)

بیشتر اپلیکیشن‌ها می‌توانند این بخش را نادیده بگیرند. فقط در صورتی این روش را به‌کار ببرید که minSdkVersion اپ شما بین ۹ و ۱۳ است.

نمایش Session Tracking برای API Level 9 تا 13

نکته

در صورت امکان minSdkVersion را به ۱۴ یا بالاتر ارتقا دهید تا بتوانید از ActivityLifecycleCallbacks استفاده کنید.

برای API Level پایین‌تر از ۱۴، باید در هر Activity جداگانه Lifecycle را مدیریت کنید:

1. در onResume هر Activity، متد AdTrace.onResume() را فراخوانی کنید.
2. در onPause هر Activity، متد AdTrace.onPause() را فراخوانی کنید.
3. این کار را برای تمام Activityهای اپ انجام دهید. می‌توانید از یک Base Activity مشترک استفاده کنید.

Java

YourActivity.java

import io.adtrace.sdk.AdTrace;

public class YourActivity extends Activity {
    @Override
    protected void onResume() {
        super.onResume();
        AdTrace.onResume();
    }

    @Override
    protected void onPause() {
        super.onPause();
        AdTrace.onPause();
    }
}

Kotlin

YourActivity.kt

import io.adtrace.sdk.AdTrace

class YourActivity : Activity() {
    override fun onResume() {
        super.onResume()
        AdTrace.onResume()
    }

    override fun onPause() {
        super.onPause()
        AdTrace.onPause()
    }
}

۸. WebBridge

اختیاری: این بخش فقط برای اپ‌هایی است که از Android WebView استفاده می‌کنند.

• اگر اپ شما Native-only است، مستقیماً به ۹. تست یکپارچه‌سازی بروید.
• اگر از TWA (Trusted Web Activity) استفاده می‌کنید، از مستندات TWA استفاده کنید. WebBridge برای TWA مناسب نیست.

اگر اپ شما محتوا را داخل WebView بارگذاری می‌کند و نیاز دارید فعالیت‌های لایه وب توسط ادتریس ثبت شود، راهنمای WebBridge (WebView) را دنبال کنید. این راهنما شامل موارد زیر است:

• Case A (فقط WebBridge): مقداردهی اولیه SDK از طریق JavaScript
• Case B (Hybrid): مقداردهی اولیه از Native + ردیابی از Native و JavaScript
• نحوه ثبت Bridge، فایل‌های JavaScript، APIها و عیب‌یابی

یک نمونه SDK در هر Process

ادتریس را فقط یک‌بار در هر Process مقداردهی کنید: چه از Native و چه از JavaScript. فراخوانی دوباره onCreate پیام AdTrace already initialized را در Logها نمایش می‌دهد.

برای مشاهده نمونه عملی به اپ نمونه WebBridge مراجعه کنید.

۹. تست یکپارچه‌سازی

قبل از اینکه Sessionها و Eventها به‌درستی در ادتریس نمایش داده شوند، باید یک Install موفق ثبت شده باشد: یعنی اولین باز شدن اپ پس از نصب. برای تأیید صحت یکپارچه‌سازی مراحل زیر را انجام دهید.

آماده‌سازی دستگاه تست

برای ایجاد یک Install واقعی در زمان تست:

1. از دستگاهی استفاده کنید که اپ شما روی آن نصب نشده است، یا اپ را ابتدا حذف کنید.
2. Google Advertising ID (gps_adid) را Reset کنید:
   • مسیر: Settings → Google → Ads → Google Advertising ID
   • یا گزینه Reset advertising ID را انتخاب کنید.
3. اپ را دوباره نصب کرده و باز کنید.

Emulator

اگر از Emulator استفاده می‌کنید، از یک AVD Image که Google Play دارد استفاده کنید. بدون Google Play، gps_adid معتبر در دسترس نیست.

مقدار gps_adid را می‌توانید از مسیر Settings → Google → Ads مشاهده کنید.

تست در پنل ادتریس

1. مقدار Google Advertising ID دستگاه را از Settings → Google → Ads کپی کنید.
2. وارد پنل ادتریس شوید و اپلیکیشن خود را انتخاب کنید.
3. به Settings → Testing Console بروید.
4. شناسه دستگاه را وارد کنید، نوع شناسه را gps_adid انتخاب کنید.
5. بررسی کنید که آیا Install برای آن دستگاه ثبت شده است یا نه.

اگر Install ثبت نشده بود:

• مراحل راه‌اندازی را مجدداً مرور کنید.
• نمونه‌پروژه‌ها را بررسی کنید.
• با یک دستگاه تست دوباره تست کنید.

تست با Logها (اختیاری)

1. سطح Log را verbose قرار دهید و مقدار environment را ENVIRONMENT_SANDBOX تنظیم کنید.
2. دستگاه را متصل کنید و Logcat را با تگ AdTrace فیلتر کنید.
3. اپ را حذف کنید، در صورت نیاز Advertising ID را Reset کنید، سپس دوباره نصب کرده و اجرا کنید.
4. در پاسخ سرور به دنبال مقدار adid بگردید. دریافت adid به معنای ثبت موفق Install است.

Logcat response (example)

"adid" : "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"

۱۰. آماده‌سازی برای انتشار (Production)

پس از اتمام تست و قبل از انتشار اپ، تنظیمات زیر را در AdTraceConfig اعمال کنید:

1. سطح Log را متناسب با نیاز Production تنظیم کنید تا لاگ‌های غیرضروری در محیط واقعی نمایش داده نشوند.
2. مقدار environment را به AdTraceConfig.ENVIRONMENT_PRODUCTION تغییر دهید.

Java

import io.adtrace.sdk.AdTrace;
import io.adtrace.sdk.AdTraceConfig;
import io.adtrace.sdk.LogLevel;

String appToken = "{YourAppToken}";
String environment = AdTraceConfig.ENVIRONMENT_PRODUCTION;
AdTraceConfig config = new AdTraceConfig(this, appToken, environment);
config.setLogLevel(LogLevel.WARN);
AdTrace.onCreate(config);

Kotlin

import io.adtrace.sdk.AdTrace
import io.adtrace.sdk.AdTraceConfig
import io.adtrace.sdk.LogLevel

val appToken = "{YourAppToken}"
val environment = AdTraceConfig.ENVIRONMENT_PRODUCTION
val config = AdTraceConfig(this, appToken, environment)
config.setLogLevel(LogLevel.WARN)
AdTrace.onCreate(config)

ترافیک Sandbox و Production در پنل ادتریس از هم جدا هستند، بنابراین داده‌های تست از کاربران واقعی قابل تمایز است.

چک‌لیست

پیش از رفتن به مرحله بعد، موارد زیر را تأیید کنید:

• وابستگی SDK ادتریس به build.gradle اضافه شده
• Google Play Services Ads Identifier اضافه شده (اپ‌های Play Store)
• کتابخانه Install Referrer اضافه شده (اپ‌های Play Store)
• Permissionهای لازم در AndroidManifest.xml تعریف شده
• Ruleهای ProGuard / R8 اضافه شده (در صورت استفاده)
• SDK در کلاس Application مقداردهی اولیه شده
• Session Tracking با onResume / onPause پیکربندی شده
• Install موفق در Testing Console یا از طریق Logها تأیید شده
• ENVIRONMENT_PRODUCTION قبل از انتشار تنظیم شده

گام بعدی

برای ارسال Eventهای سفارشی از اپ اندروید، راهنمای ردیابی رویداد (Event Tracking) را دنبال کنید.