نسخه: 2.6.0

شروع با TWA SDK

این راهنما مراحل اولیه راه‌اندازی Adtrace در یک اپ Trusted Web Activity (TWA) را توضیح می‌دهد. Shell نیتیو Android را پیکربندی می‌کنید، شناسه‌های دستگاه را از طریق launch URL به Web SDK منتقل می‌کنید، Web SDK را مقداردهی اولیه می‌کنید و تأیید می‌کنید که یکپارچه‌سازی موفق بوده است. در پایان این راهنما، اپ TWA شما آماده ردیابی نصب‌ها، session‌ها و رویدادها از لایه وب خواهد بود.

نحوه کار TWA با Adtrace

اپ‌های Trusted Web Activity (TWA) یک رابط کاربری وب را درون یک shell نیتیو Android بارگذاری می‌کنند. برخلاف WebView با پلاگین WebBridge، پس از راه‌اندازی هیچ کانال پایداری بین کد نیتیو Android و صفحه وب بارگذاری‌شده وجود ندارد.

برای Adtrace این به معنای:

۱. Android نیتیو شناسه‌های دستگاه (مثلاً gps_adid) را قبل از باز شدن TWA می‌خواند. ۲. پارامترهای query در launch URL تنها راه قابل اطمینان برای ارسال آن IDها به وب‌اپ هستند. ۳. Web SDK ترافیک نصب، session و رویداد را از لایه وب پس از دریافت IDها توسط initSdk ارسال می‌کند.

ارسال gps_adid از native به web الزامی است

همیشه gps_adid را از shell نیتیو Android به لایه وب بفرستید (launch URL → initSdk). این مرحله برای attribution در TWA حیاتی است. اگر نباشد، نصب‌ها ممکن است درست attribute نشوند و نمی‌توانید دستگاه را با gps_adid در Testing Console به‌طور قابل‌اطمینان تأیید کنید.

برای یک پیاده‌سازی مرجع کاری به پروژه نمونه TWA مراجعه کنید.

رویکردهای launcher TWA (پس‌زمینه)

Google سه راه رایج برای راه‌اندازی TWA ارائه می‌دهد. Adtrace نیاز به کد دستی دارد تا بتوانید راه‌اندازی را تا آماده شدن شناسه‌های دستگاه به تأخیر بیندازید.

رویکرد	پشتیبانی Adtrace	یادداشت‌ها
Manifest اعلانی (`LauncherActivity` فقط در XML)	پشتیبانی نمی‌شود	نمی‌تواند راه‌اندازی را به تأخیر بیندازد یا پارامترهای query اضافه کند
Activity launcher سفارشی (زیرکلاس `LauncherActivity`)	توصیه شده	این راهنما از این رویکرد استفاده می‌کند
کاملاً دستی (`TrustedWebActivityIntentBuilder`)	پشتیبانی می‌شود	هنگامی که TWA از یک دکمه نیتیو یا جریان سفارشی باز می‌شود استفاده کنید

کتابخانه‌های اصلی Google:

androidx.browser:browser: Custom Tabs و اجزای TWA سطح پایین
com.google.androidbrowserhelper:androidbrowserhelper: splash screen، fallbackها و کمکی‌های launcher

Wrapper‌های TWA فقط اعلانی با Adtrace کار نمی‌کنند

اگر اپ شما PWA را بلافاصله از manifest بدون کد سفارشی راه‌اندازی می‌کند، نمی‌توانید gps_adid را به Web SDK منتقل کنید. به جای آن از یک activity launcher سفارشی استفاده کنید.

۱. افزودن وابستگی‌ها

کمکی TWA، Adtrace Android SDK (برای getGoogleAdId) و Google Play Services Ads Identifier را به build.gradle اپ خود اضافه کنید:

build.gradle
dependencies {
    implementation 'com.google.androidbrowserhelper:androidbrowserhelper:2.6.2'
    implementation 'io.adtrace:android-sdk:2.6.1'
    implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
}

نسخه‌ها را با آخرین نسخه‌های سازگار از Maven Central و صفحه releases Android SDK جایگزین کنید.

۲. راه‌اندازی Proguard

اگر از Proguard یا R8 استفاده می‌کنید، این قوانین را اضافه کنید تا کلاس‌های مورد نیاز حذف نشوند:

proguard-rules.pro
-keep class io.adtrace.sdk.** { *; }
-keep interface io.adtrace.sdk.** { *; }
-keep enum 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();
}

۳. دریافت شناسه‌های دستگاه و ساخت launch URL

در activity اصلی launcher خود، gps_adid (و هر ID دیگری که نیاز دارید) را قبل از باز کردن TWA بخوانید. آن‌ها را به عنوان پارامترهای query در launch URL اضافه کنید.

متد	هدف
`shouldLaunchImmediately()` → `false`	جلوگیری از راه‌اندازی خودکار تا آماده شدن داده‌های نیتیو
`AdTrace.getGoogleAdId(...)`	خواندن `gps_adid` از Google Play Services
`launchTwa()`	باز کردن TWA پس از آماده شدن IDها
`getLaunchingUrl()`	برگرداندن PWA URL با پارامترهای query اضافه‌شده

Java
Kotlin

LauncherActivity.java
package com.example.twa;

import android.net.Uri;
import android.os.Bundle;

import io.adtrace.sdk.AdTrace;

public class LauncherActivity extends com.google.androidbrowserhelper.trusted.LauncherActivity {

    private String mGoogleAdId;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        AdTrace.getGoogleAdId(this, googleAdId -> {
            mGoogleAdId = googleAdId != null ? googleAdId : "";
            launchTwa(); // فقط هنگامی که تمام پارامترهای مورد نیاز آماده هستند فراخوانی کنید
        });
    }

    @Override
    protected boolean shouldLaunchImmediately() {
        return false;
    }

    @Override
    protected Uri getLaunchingUrl() {
        Uri base = Uri.parse("YOUR_WEB_PAGE_BASE_URL");
        return base.buildUpon()
                .appendQueryParameter("gps_adid", mGoogleAdId != null ? mGoogleAdId : "")
                .build();
    }
}

LauncherActivity.kt
package com.example.twa

import android.net.Uri
import android.os.Bundle
import io.adtrace.sdk.AdTrace

class LauncherActivity : com.google.androidbrowserhelper.trusted.LauncherActivity() {

    private var googleAdId: String? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        AdTrace.getGoogleAdId(this) { adId ->
            googleAdId = adId ?: ""
            launchTwa() // فقط هنگامی که تمام پارامترهای مورد نیاز آماده هستند فراخوانی کنید
        }
    }

    override fun shouldLaunchImmediately(): Boolean = false

    override fun getLaunchingUrl(): Uri {
        val base = Uri.parse("YOUR_WEB_PAGE_BASE_URL")
        return base.buildUpon()
            .appendQueryParameter("gps_adid", googleAdId ?: "")
            .build()
    }
}

از همان key پارامتر query در نیتیو و وب استفاده کنید (مثلاً gps_adid). می‌توانید IDهای اضافی یا push token را به همین شکل اضافه کنید. اگر push token هم دریافت می‌کنید، launchTwa() را فقط پس از آماده شدن هر دو مقدار فراخوانی کنید.

قبل از هر redirect، پارامترهای query را بخوانید

اگر وب‌اپ شما کاربران احراز هویت نشده را به /login هدایت می‌کند، پارامترهای launch URL ممکن است گم شوند. به سوالات متداول مراجعه کنید.

۴. ایجاد کلاس Application

اگر ندارید یک کلاس سراسری Application ایجاد کنید. برای جریان TWA پایه نیاز به init نیتیو Adtrace نیست؛ کد نیتیو فقط شناسه‌های دستگاه را می‌خواند.

Java
Kotlin

GlobalApplication.java
package com.example.twa;

import android.app.Application;

public class GlobalApplication extends Application {
}

GlobalApplication.kt
package com.example.twa

import android.app.Application

class GlobalApplication : Application()

کلاس را در AndroidManifest.xml ثبت کنید:

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

۵. افزودن مجوزها و پیکربندی AndroidManifest.xml

مجوزهای الزامی

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

Google Advertising ID (`AD_ID`)

اگر اپ شما Android 12 (API level 31) یا بالاتر را هدف قرار می‌دهد، این را اضافه کنید:

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

مثال کامل manifest

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.twa">

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

    <application
        android:name=".GlobalApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.AppCompat.Light.NoActionBar"
        android:usesCleartextTraffic="true">

        <activity
            android:name=".LauncherActivity"
            android:exported="true"
            android:launchMode="singleTask"
            android:theme="@android:style/Theme.Translucent.NoTitleBar">
            <meta-data
                android:name="android.support.customtabs.trusted.DEFAULT_URL"
                android:value="YOUR_WEB_PAGE_BASE_URL" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" android:host="YOUR_DEEP_LINK_BASE_URL" />
            </intent-filter>
        </activity>

        <meta-data
            android:name="asset_statements"
            android:resource="@string/asset_statements" />

        <meta-data
            android:name="web_manifest_url"
            android:value="YOUR_TWA_BASE_HOST_URL/manifest.json" />

        <meta-data
            android:name="twa_generator"
            android:value="pwabuilder" />

    </application>
</manifest>

URLهای placeholder را با PWA host، deep link host و مسیر web manifest خود جایگزین کنید.

۶. افزودن manifest وب‌اپ

manifest.json را در وب‌اپ خود ایجاد کنید (یا پوشه assets، بسته به راه‌اندازی TWA):

manifest.json
{
  "name": "TWA App",
  "short_name": "TWA App",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff",
  "icons": [
    {
      "src": "/icons/icon-192.svg",
      "sizes": "192x192",
      "type": "image/svg+xml"
    },
    {
      "src": "/icons/icon-512.svg",
      "sizes": "512x512",
      "type": "image/svg+xml"
    }
  ]
}

۷. مقداردهی اولیه Web SDK

ارسال gps_adid از native به web الزامی است

gps_adid را از launch URL بخوانید و به initSdk پاس دهید. وقتی gps_adid از دستگاه در دسترس است، initSdk را بدون آن فراخوانی نکنید.

Adtrace Web SDK را در PWA خود نصب و بارگذاری کنید. برای راه‌اندازی script، نصب NPM و گزینه‌های کامل initSdk به راهنمای یکپارچه‌سازی Web SDK مراجعه کنید.

برای TWA، پارامترهای query در launch URL را قبل از فراخوانی initSdk parse کنید:

مقداردهی اولیه وب‌اپ
function getQueryParam(name) {
  const params = new URLSearchParams(window.location.search);
  return params.get(name);
}

const gpsAdid = getQueryParam('gps_adid'); // باید با key نیتیو مطابقت داشته باشد

Adtrace.initSdk({
  appToken: 'YOUR_APP_TOKEN',
  environment: 'sandbox', // قبل از انتشار از 'production' استفاده کنید
  gps_adid: gpsAdid,
});

YOUR_APP_TOKEN را با توکن اپ خود از پنل Adtrace جایگزین کنید.

در حین تست از environment: 'sandbox' و قبل از انتشار از 'production' استفاده کنید.

پارامترهای شناسه دستگاه TWA

هر IDی که به launch URL نیتیو اضافه کرده‌اید را به initSdk منتقل کنید:

پارامتر	توضیحات
`gps_adid`	Google Advertising ID (Android)
`idfa`	IDFA (iOS، در صورت کاربرد)
`oaid`	Huawei Advertising ID
`android_uuid`	Android ID
`fb_id`	Facebook advertising ID
`fire_adid`	Amazon Advertising ID
`persistent_ios_uuid`	Persistent iOS ID
`ios_uuid`	iOS ID
`idfv`	IDFV
`primary_dedupe_token`	Primary dedupe token
`push_token`	Push token ارسال‌شده با هر درخواست

نکته

پس از مقداردهی اولیه Web SDK، برای رویدادها، callbackها، partner parameterها و attribution، ادامه را در لایه وب دنبال کنید.

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

یک نصب موفق (اولین باز شدن پس از نصب) باید ثبت شود تا session‌ها و رویدادها به درستی در Adtrace نمایش داده شوند. از مراحل زیر برای تأیید یکپارچه‌سازی استفاده کنید.

روی دستگاه موبایل تست کنید

نصب فقط هنگامی ثبت می‌شود که اپ روی یک گوشی موبایل واقعی یا شبیه‌ساز با پشتیبانی Google Play اجرا شود. روی سایر انواع دستگاه‌ها، Adtrace دستگاه را غیرموبایل می‌داند و نصب ثبت نمی‌کند.

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

برای راه‌اندازی یک نصب واقعی برای تست:

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

اگر از شبیه‌ساز استفاده می‌کنید، از یک image AVD که شامل Google Play است استفاده کنید. شبیه‌سازهای بدون Google Play نمی‌توانند یک Google Advertising ID معتبر ارائه دهند.

می‌توانید Google Advertising ID خود (gps_adid) را در دستگاه در Settings → Google → Ads پیدا کنید.

تست در پنل Adtrace

اگر از پنل Adtrace استفاده می‌کنید:

۱. Google Advertising ID دستگاه خود (gps_adid) را از Settings → Google → Ads کپی کنید. ۲. پنل Adtrace را باز کنید، اپ خود را انتخاب کنید، سپس به Settings → Testing Console بروید. ۳. شناسه دستگاه را وارد کنید، نوع ID (gps_adid) را انتخاب کنید و بررسی کنید آیا نصبی برای آن دستگاه ثبت شده است.

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

اگر gps_adid گم است یا نصب هنوز شکست می‌خورد، به سوالات متداول مراجعه کنید.

چک‌لیست

قبل از ادامه، تأیید کنید موارد زیر را کامل کرده‌اید:

وابستگی‌های TWA helper، Adtrace Android SDK و Play Services Ads Identifier اضافه شدند
قوانین keep Proguard/R8 اضافه شدند (اگر از Proguard یا R8 استفاده می‌کنید)
shouldLaunchImmediately() روی false تنظیم شد و launchTwa() تا آماده شدن IDها به تأخیر افتاد
شناسه‌های دستگاه با keyهای مطابق در نیتیو و وب به launch URL اضافه شدند
مجوزهای INTERNET، ACCESS_NETWORK_STATE و AD_ID اعلان شدند
LauncherActivity و GlobalApplication در AndroidManifest.xml پیکربندی شدند
Web SDK با پارامترهای query parse‌شده در اولین بارگذاری صفحه مقداردهی اولیه شد
یک نصب موفق در Testing Console روی دستگاه موبایل تأیید شد

نحوه کار TWA با Adtrace​

۱. افزودن وابستگی‌ها​

۲. راه‌اندازی Proguard​

۳. دریافت شناسه‌های دستگاه و ساخت launch URL​

۴. ایجاد کلاس Application​

۵. افزودن مجوزها و پیکربندی AndroidManifest.xml​

مجوزهای الزامی​

Google Advertising ID (AD_ID)​

مثال کامل manifest​

۶. افزودن manifest وب‌اپ​

۷. مقداردهی اولیه Web SDK​

پارامترهای شناسه دستگاه TWA​

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

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

تست در پنل Adtrace​

چک‌لیست​

مراحل بعدی​

مطالب مرتبط​