WebBridge (WebView)

راهنمای فنی یکپارچه‌سازی Adtrace WebBridge در اپلیکیشن Android که محتوا را در WebView بارگذاری می‌کند.

هماهنگ با Adtrace Android SDK / WebBridge v3.0.1.

برای اپ‌های فقط native (بدون WebView)، به شروع کار با Android SDK مراجعه کنید.
برای Trusted Web Activity، از مستندات TWA استفاده کنید. از WebBridge برای TWA استفاده نکنید.

اپ نمونه: example-app-webbridge.
فایل‌های JS: فایل‌های WebBridge plugin.

۱. مرور کلی

WebBridge به HTML/JavaScript داخل WebView اجازه می‌دهد با همان native Adtrace SDK که توسط کد Android استفاده می‌شود، ارتباط برقرار کند.

یک نمونه SDK

تنها یک نمونه SDK در هر پردازش اپ وجود دارد. آن را یک بار مقداردهی اولیه کنید، یا از JavaScript یا از native Android.

فراخوانی دوباره onCreate پیام لاگ می‌دهد: AdTrace already initialized.

۲. انتخاب حالت یکپارچه‌سازی

آیا از کد Android native رویدادهای Adtrace را ردیابی می‌کنید (Activity / Application / Service)?

	Case A: فقط WebBridge	Case B: ترکیبی
رویدادهای native؟	خیر. ردیابی فقط از HTML/JS	بله. Activities/Services قبلاً AdTrace.trackEvent را فراخوانی می‌کنند
چه کسی AdTrace.onCreate را فراخوانی می‌کند؟	JavaScript در صفحه WebView	Native (Application / Activity اولیه)
مقداردهی اولیه Application native؟	اختیاری / برای Adtrace در Case A لازم نیست	الزامی
AdTrace.onCreate از JS؟	بله (پس از ثبت bridge)	خیر. از آن صرف‌نظر کنید
AdTrace.trackEvent از native؟	استفاده نمی‌شود	بله
AdTrace.trackEvent از JS؟	بله	بله (همان SDK)
اپ نمونه	مرورگر درون‌اپ / قیف عمدتاً HTML	رابط کاربری native مختلط + صفحات WebView

۳. تنظیمات مشترک (هر دو حالت)

تنظیمات اصلی SDK (Maven / AAR، Google Play Services، Install Referrer) را طبق شروع کار با Android SDK انجام دهید. سپس WebBridge plugin را زیر اضافه کنید.

پیش‌نیازها

مورد	نیاز
minSdkVersion	21 (Android 5.0 / Lollipop)
Core SDK	io.adtrace:android-sdk (همان نسخه webbridge)
Plugin	io.adtrace:android-sdk-plugin-webbridge
WebView	JavaScript فعال
مجوزها	INTERNET، ACCESS_NETWORK_STATE، AD_ID (API 31+)
Google Play	play-services-ads-identifier + installreferrer توصیه می‌شود

Gradle

build.gradle

dependencies {
    implementation 'io.adtrace:android-sdk:3.0.1'

    // اگر از Adtrace SDK درون web views اپ خود استفاده می‌کنید، موارد زیر را اضافه کنید
    implementation 'io.adtrace:android-sdk-plugin-webbridge:3.0.1'

    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.0'
}

می‌توانید WebBridge AAR/JAR را از صفحه releases گیت‌هاب دانلود کنید.

مهم

حداقل سطح Android API پشتیبانی شده برای WebBridge plugin 21 (Android 5.0 / Lollipop) است. از WebBridge برای اپ‌های 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" />

فایل‌های JavaScript

توسط WebBridge plugin ارسال می‌شوند (در APK ادغام می‌شوند):

فایل	نقش
adtrace.js	API اصلی AdTrace در JS
adtrace_config.js	AdTraceConfig
adtrace_event.js	AdTraceEvent
adtrace_third_party_sharing.js	کمکی اشتراک‌گذاری با اشخاص ثالث

ترتیب include:

<script src="adtrace_event.js"></script>
<script src="adtrace_third_party_sharing.js"></script>
<script src="adtrace_config.js"></script>
<script src="adtrace.js"></script>

برای HTML ریموت، این فایل‌ها را کنار صفحه خود host کنید (یا از URL مطلق استفاده کنید). به فایل‌های WebBridge JS مراجعه کنید.

اتصال WebView

این مرحله برای هر دو Case A و Case B الزامی است. آن را در Activity که WebView را host می‌کند انجام دهید.

قبل از شروع، یک reference به object مربوط به WebView خود بگیرید. سپس:

1. webView.getSettings().setJavaScriptEnabled(true) را فراخوانی کنید تا JavaScript در WebView فعال شود.
2. نمونه پیش‌فرض AdTraceBridge را با AdTraceBridge.registerAndGetInstance(getApplication(), webView) راه‌اندازی کنید. این bridge Adtrace را به عنوان یک JavaScript interface در WebView ثبت می‌کند.
3. اگر بعداً نیاز به اتصال WebView دیگری دارید، AdTraceBridge.setWebView() را فراخوانی کنید.
4. در onDestroy برای لغو ثبت bridge و WebView، AdTraceBridge.unregister() را فراخوانی کنید.

مهم

AdTraceBridge.registerAndGetInstance را قبل از webView.loadUrl(...) فراخوانی کنید. در غیر این صورت JavaScript نمی‌تواند AdTraceBridge را ببیند.

پس از این مراحل، Activity شما باید این‌گونه باشد:

Java

WebViewActivity.java

public class WebViewActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_webview);

        WebView webView = findViewById(R.id.webView);
        webView.getSettings().setJavaScriptEnabled(true);
        webView.setWebChromeClient(new WebChromeClient());
        webView.setWebViewClient(new WebViewClient());

        AdTraceBridge.registerAndGetInstance(getApplication(), webView);
        webView.loadUrl("file:///android_asset/your-page.html");
    }

    @Override
    protected void onDestroy() {
        AdTraceBridge.unregister();
        super.onDestroy();
    }
}

Kotlin

WebViewActivity.kt

class WebViewActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_webview)

        val webView = findViewById<WebView>(R.id.webView)
        webView.settings.javaScriptEnabled = true
        webView.webChromeClient = WebChromeClient()
        webView.webViewClient = WebViewClient()

        AdTraceBridge.registerAndGetInstance(application, webView)
        webView.loadUrl("file:///android_asset/your-page.html")
    }

    override fun onDestroy() {
        AdTraceBridge.unregister()
        super.onDestroy()
    }
}

تنظیم Proguard

اگر از Proguard استفاده می‌کنید، این خطوط را به فایل Proguard اضافه کنید:

proguard-rules.pro

-keep class io.adtrace.sdk.** { *; }
-keep class io.adtrace.sdk.webbridge.** { *; }
-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 Store منتشر نمی‌کنید، از قوانین بسته io.adtrace.sdk زیر استفاده کنید:

proguard-rules.pro

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

۴. Case A: فقط WebBridge (بدون رویداد native)

از Case A استفاده کنید وقتی اپ Android شما محتوا را در WebView بارگذاری می‌کند و تمام ردیابی Adtrace (مقداردهی اولیه، Session، رویداد) از HTML/JavaScript اجرا می‌شود.

این Trusted Web Activity (TWA) نیست. برای TWA، به مستندات TWA مراجعه کنید.

در سمت native فقط:

1. WebView را host می‌کنید
2. AdTraceBridge را قبل از بارگذاری صفحه ثبت می‌کنید

AdTrace.onCreate یا AdTrace.trackEvent از native را فراخوانی نمی‌کنید.

سمت native (فقط bridge)

بدون مقداردهی اولیه Adtrace در Application. بدون trackEvent از native.

Bridge را طبق اتصال WebView ثبت کنید، سپس صفحه HTML خود را بارگذاری کنید. در Case A نیازی به android:name=".GlobalApplication" برای Adtrace ندارید.

سمت JavaScript (مقداردهی اولیه)

اسکریپت‌های WebBridge را بارگذاری کنید، AdTraceConfig بسازید، سپس AdTrace.onCreate را یک بار فراخوانی کنید:

<script src="adtrace_event.js"></script>
<script src="adtrace_third_party_sharing.js"></script>
<script src="adtrace_config.js"></script>
<script src="adtrace.js"></script>

<script>
  var config = new AdTraceConfig(
      '{YourAppToken}',
      AdTraceConfig.EnvironmentSandbox
  );
  AdTrace.onCreate(config);
</script>

{YourAppToken} را با token اپ خود از پنل Adtrace جایگزین کنید.

از AdTraceConfig.EnvironmentSandbox در حین تست و AdTraceConfig.EnvironmentProduction قبل از انتشار استفاده کنید.

چگونه از ویژگی‌های Adtrace در JavaScript استفاده کنیم

مثال‌های ویژگی را در این صفحه تکرار نکنید. برای هر ویژگی Adtrace، صفحه مستندات Android آن ویژگی را باز کنید و تب Javascript را انتخاب کنید.

هدف	این صفحه را باز کنید	سپس
سطح لاگ	تنظیم سطح لاگ	Javascript را انتخاب کنید
تأخیر شروع / event buffering / offline / disable	پیکربندی	صفحه ویژگی را باز کنید → Javascript
اطلاعات Attribution	ارسال اطلاعات Callback · Attribution کاربر	Javascript را انتخاب کنید

الگو برای توسعه‌دهندگان:

1. ویژگی را در Configuration، Event tracking، یا Additional features پیدا کنید.
2. صفحه آن ویژگی را باز کنید.
3. تب Javascript را انتخاب کنید.
4. نمونه JS را در HTML WebView خود کپی کنید (پس از AdTrace.onCreate در Case A، یا در Case B بدون onCreate دوم).

نکته

در Case A، گزینه‌های config و Callback را در AdTraceConfig قبل از AdTrace.onCreate تنظیم کنید. در Case B، همان گزینه‌ها را در native AdTraceConfig تنظیم کنید.

ترتیب عملیات در Case A

1. JavaScript را در WebView فعال کنید
2. AdTraceBridge.registerAndGetInstance(application, webView)
3. loadUrl(...)
4. HTML فایل‌های adtrace*.js را بارگذاری می‌کند
5. JS: AdTrace.onCreate(config) یک بار
6. از صفحات ویژگی (تب Javascript) برای رویدادها، سطح لاگ، Callback‌ها و APIهای دیگر استفاده کنید
7. Activity onDestroy → AdTraceBridge.unregister()

چک‌لیست Case A

• وابستگی‌ها: core SDK + WebBridge plugin
• مجوزها: INTERNET، ACCESS_NETWORK_STATE، AD_ID
• Bridge قبل از بارگذاری صفحه ثبت شده
• JS AdTrace.onCreate را یک بار فراخوانی می‌کند
• کد native AdTrace.onCreate را فراخوانی نمی‌کند
• Logcat با تگ AdTrace نصب/Session را پس از بارگذاری صفحه نشان می‌دهد

۵. Case B: ترکیبی (رویدادهای native + Web Bridge)

وقتی کد Android native قبلاً (یا همزمان) رویدادها را ردیابی می‌کند و HTML WebView باید رویدادهای بیشتری به همان SDK ارسال کند از این حالت استفاده کنید.

ابتدا تنظیمات مشترک را کامل کنید، سپس native را طبق شروع کار با Android SDK مقداردهی اولیه کنید.

مرحله B1: مقداردهی اولیه در سمت native (یک بار)

GlobalApplication.java

public class GlobalApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        AdTraceConfig config = new AdTraceConfig(
                this,
                "{YourAppToken}",
                AdTraceConfig.ENVIRONMENT_SANDBOX);
        config.setLogLevel(LogLevel.VERBOSE);
        config.setSendInBackground(true);
        // در صورت نیاز، Callback های native را اینجا تنظیم کنید:
        // config.setOnEventTrackingSucceededListener(...);

        AdTrace.onCreate(config);
        registerActivityLifecycleCallbacks(new AdTraceLifecycleCallbacks());
    }
}

<application android:name=".GlobalApplication" ...>

Install referrer، Google Play Services، و ردیابی Session native را طبق شروع کار با Android SDK کامل کنید.

مرحله B2: ردیابی رویدادها از کد native

AdTraceEvent event = new AdTraceEvent("{eventToken}");
AdTrace.trackEvent(event);

مرحله B3: ثبت Web Bridge (بدون مقداردهی اولیه دوم)

Bridge را طبق اتصال WebView ثبت کنید. Bridge JS را به SDK native که قبلاً در حال اجرا است متصل می‌کند. AdTrace.onCreate را دوباره از JavaScript فراخوانی نکنید.

مرحله B4: ردیابی از JavaScript (بدون onCreate)

اسکریپت‌های WebBridge را بارگذاری کنید. AdTrace.onCreate را فراخوانی نکنید (native قبلاً این کار را کرده).

برای رویدادها و ویژگی‌های دیگر، از تب Javascript در هر صفحه ویژگی استفاده کنید. به چگونه از ویژگی‌های Adtrace در JavaScript استفاده کنیم مراجعه کنید.

الگوی حداقلی:

<script src="adtrace_event.js"></script>
<script src="adtrace_config.js"></script>
<script src="adtrace.js"></script>
<script>
  // AdTrace.onCreate را فراخوانی نکنید. Native قبلاً این کار را کرده.
  // ردیابی / پیکربندی با استفاده از نمونه‌های JS از هر صفحه ویژگی.
</script>

چه کاری کجا انجام می‌شود (Case B)

موضوع	Android Native	JavaScript (bridge)
AdTrace.onCreate + چرخه حیات Session	بله	خیر
رویدادها از Activities / Services	بله	:
رویدادها از HTML / قیف‌های web	:	بله
Callback ها / سطح لاگ	در native AdTraceConfig	فقط اگر از Case A استفاده کردید
Install referrer / وابستگی‌های Play	بله	:
Deep link از Intent	AdTrace.appWillOpenUrl(uri, context)	AdTrace.appWillOpenUrl(url) اگر صفحه URL دارد

چک‌لیست Case B

• یک AdTrace.onCreate از native (Application توصیه می‌شود)
• همان app token / environment در همه جا
• رویدادهای native از طریق io.adtrace.sdk.AdTrace / AdTraceEvent
• Bridge قبل از بارگذاری HTML ثبت شده
• HTML AdTrace.onCreate را فراخوانی نمی‌کند
• HTML همچنان AdTrace.trackEvent (و سایر JS API ها) را در صورت نیاز فراخوانی می‌کند
• AdTraceBridge.unregister() در onDestroy Activity WebView

۶. ویژگی‌های JavaScript (از صفحات ویژگی استفاده کنید)

پس از شروع SDK (JS onCreate در Case A، یا native onCreate در Case B)، از ویژگی‌های Adtrace از صفحه مستندات Android مطابق استفاده کنید.

چه زمانی AdTrace.onCreate را از JS فراخوانی کنیم

Case	AdTrace.onCreate از JS فراخوانی شود؟
A: فقط WebBridge	بله
B: ترکیبی	خیر

کجا نمونه‌های JS پیدا کنیم

برای هر ویژگی:

1. صفحه ویژگی Android را باز کنید (Configuration، Event tracking، Additional features، Deep linking).
2. تب Javascript را انتخاب کنید.
3. نمونه را در HTML WebView خود کپی کنید.

برای نقشه ویژگی → صفحه به چگونه از ویژگی‌های Adtrace در JavaScript استفاده کنیم مراجعه کنید.

نمونه‌ها:

• سطح لاگ → تنظیم سطح لاگ → Javascript
• رویدادها → ردیابی رویدادها → Javascript
• پارامترهای Session → پارامترهای Session → Javascript

در Case A، تنظیمات config و Callback ها را در AdTraceConfig قبل از AdTrace.onCreate اعمال کنید.
در Case B، همان گزینه‌ها را در native AdTraceConfig اعمال کنید؛ اگر JS هرگز onCreate را فراخوانی نکند، Setter های Callback در JS روی config تأثیری ندارند.

۷. Deep link، حریم خصوصی، پیشرفته

Deep link

منبع	API
URL معروف در HTML	AdTrace.appWillOpenUrl(deeplinkUrl)
داده Intent اندروید	Native AdTrace.appWillOpenUrl(uri, context)

همچنین به Deep linking و Reattribution مراجعه کنید.

Install referrer

Play Install Referrer را در سمت native برای هر دو حالت پیکربندی کنید. به شروع کار: اضافه کردن Install Referrer مراجعه کنید.

حریم خصوصی

برای GDPR، اشتراک‌گذاری با اشخاص ثالث، رضایت اندازه‌گیری، COPPA، و اپ‌های Kids، صفحه ویژگی Android مطابق را باز کنید و از تب Javascript استفاده کنید. گزینه‌های COPPA / Kids در config که onCreate را انجام می‌دهد قرار می‌گیرند (JS در Case A، native در Case B).

بازسازی WebView

AdTraceBridge.setWebView(newWebView);

HTML ریموت

1. فایل‌های adtrace*.js را کنار صفحه خود host کنید
2. Bridge را قبل از loadUrl ثبت کنید
3. قوانین Case A یا B را برای onCreate دنبال کنید

۸. تأیید و رفع مشکل

بررسی‌های موفقیت

هر دو حالت

• Bridge قبل از بارگذاری صفحه ثبت شده
• JS فعال است؛ adtrace*.js بدون خطای 404 بارگذاری می‌شود
• Logcat با adb logcat -s AdTrace ترافیک نشان می‌دهد
• رویداد ردیابی شده Path: /event نشان می‌دهد

فقط Case A

• JS AdTrace.onCreate پس از ثبت bridge اجرا می‌شود
• بدون AdTrace.onCreate native

فقط Case B

• AdTrace.onCreate native در Application
• رویداد native هنگام ضربه زدن به UI native ظاهر می‌شود
• HTML AdTrace.onCreate را فراخوانی نمی‌کند
• بدون خط لاگ AdTrace already initialized از onCreate دوم

مشکلات رایج

علامت	دلیل احتمالی	راه‌حل
AdTrace already initialized	هم native و هم JS onCreate را فراخوانی کردند	Case A یا B را انتخاب کنید. تنها یک onCreate
AdTraceBridge در JS تعریف نشده	Bridge بعد از loadUrl، یا WebView اشتباه	قبل از بارگذاری ثبت کنید
بدون رویداد از HTML (Case B)	فراموش شدن ثبت bridge	registerAndGetInstance را فراخوانی کنید
بدون رویداد از native (Case B)	SDK هرگز شروع نشده	AdTrace.onCreate native را اضافه کنید
بدون رویداد از HTML (Case A)	onCreate از JS فراموش شده	AdTrace.onCreate را در صفحه فراخوانی کنید
Scripts خطای 404	صفحه ریموت بدون فایل‌های JS	فایل‌های adtrace*.js را host کنید
خطاهای minSdk	API کمتر از 21	minSdk را برای WebBridge افزایش دهید

۹. مرجع API

Native: AdTraceBridge

متد	توضیح
registerAndGetInstance(Application, WebView)	ثبت JavaScript interface
getDefaultInstance()	دریافت singleton
setWebView(WebView)	اتصال مجدد WebView
setApplicationContext(Application)	به‌روزرسانی context
unregister()	پایان دادن به bridge

Native: core SDK (Case B)

از io.adtrace.sdk.AdTrace، AdTraceConfig، و AdTraceEvent طبق شروع کار با Android SDK استفاده کنید.

JavaScript: AdTrace

متد	توضیح
onCreate(config)	مقداردهی اولیه SDK (فقط Case A)
trackEvent(event)	ردیابی رویداد
trackAdRevenue(source, payload)	درآمد تبلیغات
onResume / onPause	hooks Session (برای native SDK 3.0.0+ لازم نیست؛ ممکن است در Case A JS اعمال شود)
setEnabled / isEnabled	فلگ فعال‌سازی
appWillOpenUrl	Deep link
setReferrer	رشته Referrer
setOfflineMode	صف آفلاین
sendFirstPackages	پایان تأخیر شروع
add/remove/resetSession*Parameter(s)	پارامترهای Session
setPushToken	توکن FCM
gdprForgetMe / disableThirdPartySharing	حریم خصوصی
trackThirdPartySharing / trackMeasurementConsent	رضایت
getGoogleAdId / getAmazonAdId / getAdid	شناسه‌های دستگاه
getAttribution / getSdkVersion	Attribution / نسخه
teardown	پایان دادن به حالت bridge JS/native

JavaScript: AdTraceConfig / AdTraceEvent

از تب Javascript در هر صفحه ویژگی استفاده کنید. به چگونه از ویژگی‌های Adtrace در JavaScript استفاده کنیم مراجعه کنید. Setter های کامل همچنین با adtrace_config.js / adtrace_event.js در فایل‌های plugin مطابقت دارند.

مرتبط

• شروع کار با Android SDK
• Android FAQ: WebBridge
• Deep linking
• مستندات TWA (از WebBridge برای TWA استفاده نکنید)
• اپ نمونه WebBridge