Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.
مستندات فنیTrusted Web Activity (TWA)

Trusted Web Activity (TWA)

نمای کلی

از Web SDK نسخه 2.9.0، وب‌سایتی که داخل TWA اندروید باز می‌شود فراخوانی‌های متریکس خود را به‌صورت خودکار به SDK نیتیو اندروید می‌فرستد. اپلیکیشن اندروید MetrixAttributionTwaBridge را به نشست مرورگر متصل می‌کند و وب‌سایت را با METRIX_TWA=true در query string باز می‌کند؛ Web SDK این نشانه را تشخیص می‌دهد و از طریق کانال postMessage کروم متصل می‌شود. به هیچ فایل جاوااسکریپت اضافه یا راه‌اندازی پل در وب‌سایت نیازی نیست.

این روش به Chrome نسخه 115.0.5790.13 یا بالاتر و AndroidX Browser نسخه 1.6.0 یا بالاتر نیاز دارد. در TWA نمی‌توان از رابط جاوااسکریپت WebView استفاده کرد؛ در اپلیکیشن‌های WebView اندروید، Web SDK به‌جای آن از MetrixAnalyticsBridge استفاده می‌کند.

تا زمانی که پل TWA فعال است، رویدادها، درآمد، احراز هویت کاربر (authorizeUser) و ویژگی‌های کاربر توسط SDK نیتیو مدیریت می‌شوند و Web SDK مرورگر (از جمله ردیابی نشست) راه‌اندازی نمی‌شود؛ بنابراین هیچ داده‌ای دو بار ارسال نمی‌شود. بازدیدهای عادی مرورگر و PWA همچنان از ردیابی Web SDK استفاده می‌کنند.

پیکربندی اپلیکیشن اندروید

ماژول‌های AndroidX Browser، attribution، analytics و twa را به اپلیکیشن اضافه کنید. همه ماژول‌های متریکس را روی نسخه 2.10.0 نگه دارید.

dependencies { implementation("androidx.browser:browser:1.6.0") implementation("ir.metrix.twa:metrix:2.10.0") implementation("ir.metrix.attribution:metrix:2.10.0") implementation("ir.metrix.analytics:metrix:2.10.0") }

طبق راهنمای پیاده‌سازی اندروید، ir.metrix.APPLICATION_ID و ir.metrix.API_KEY را در manifest اپلیکیشن تنظیم کنید. در صورت امکان، امضای SDK را در تنظیمات نیتیو نگه دارید. سرویس را داخل <application> و بخش queries را مستقیماً داخل <manifest> قرار دهید:

<queries> <intent> <action android:name="android.support.customtabs.action.CustomTabsService" /> </intent> </queries> <application> <service android:name="androidx.browser.customtabs.PostMessageService" android:exported="true" /> </application>

تأیید مبدأ وب‌سایت

فایل https://app.example/.well-known/assetlinks.json را از طریق HTTPS منتشر کنید و نام پکیج و اثرانگشت گواهی امضای اپ اندروید را جایگزین کنید:

[ { "relation": [ "delegate_permission/common.handle_all_urls", "delegate_permission/common.use_as_origin" ], "target": { "namespace": "android_app", "package_name": "com.example.twa", "sha256_cert_fingerprints": ["YOUR:APP:SIGNING:CERTIFICATE:SHA256:FINGERPRINT"] } } ]

handle_all_urls ارتباط TWA را برقرار می‌کند و use_as_origin اجازه کانال پیام را می‌دهد. در صورت استفاده از Google Play App Signing، اثرانگشت گواهی امضای اپ را ثبت کنید؛ برای تست نسخه‌های توسعه، اثرانگشت گواهی توسعه را نیز بیفزایید. مبدأ HTTPS پل باید دقیقاً با مبدأ وب‌سایت یکسان باشد و مسیر، query یا fragment نداشته باشد.

راه‌اندازی با همان نشست مرورگر

MetrixAttributionTwaBridge را در ترد اصلی بسازید، آن را به newSession بدهید، همان نشست را به پل متصل کنید و TWA را با همان نشست اجرا کنید. URL را با METRIX_TWA=true اجرا کنید؛ خود پل مبدأ ساده را دریافت می‌کند:

private val SITE_ORIGIN = "https://app.example" private val TWA_URL = "$SITE_ORIGIN/?METRIX_TWA=true" private var bridge: MetrixAttributionTwaBridge? = null private var browserBound = false private val browserConnection = object : CustomTabsServiceConnection() { override fun onCustomTabsServiceConnected(name: ComponentName, client: CustomTabsClient) { client.warmup(0L) val currentBridge = bridge ?: return val session = client.newSession(currentBridge) ?: run { currentBridge.disconnect() launchFallback() return } currentBridge.attach(session) TrustedWebActivityIntentBuilder(Uri.parse(TWA_URL)) .build(session) .launchTrustedWebActivity(this@MainActivity) } override fun onServiceDisconnected(name: ComponentName) { bridge?.disconnect() } } private fun launchTwa() { bridge = MetrixAttributionTwaBridge( origin = SITE_ORIGIN, stateListener = MetrixAttributionTwaBridge.StateListener { state, error -> // Log READY or UNAVAILABLE, with its error, during device testing. Log.d("MetrixTwa", "Bridge: $state; error: $error") } ) val provider = CustomTabsClient.getPackageName(this, null) browserBound = provider != null && CustomTabsClient.bindCustomTabsService(this, provider, browserConnection) if (!browserBound) { bridge?.disconnect() launchFallback() } } private fun launchFallback() { // No bridge is attached here, so open the site without the TWA marker. CustomTabsIntent.Builder().build().launchUrl(this, Uri.parse(SITE_ORIGIN)) finish() } override fun onDestroy() { bridge?.close() if (browserBound) unbindService(browserConnection) super.onDestroy() }

این نمونه در یک AppCompatActivity قرار می‌گیرد و به importهای ComponentName، Uri، Log، CustomTabsClient، CustomTabsIntent، CustomTabsServiceConnection، TrustedWebActivityIntentBuilder و ir.metrix.twa.MetrixAttributionTwaBridge نیاز دارد. launchTwa() را از onCreate فراخوانی کنید. اگر Bubblewrap یا Android Browser Helper مالک callback نشست است، callbackهای تأیید ارتباط، ناوبری، آماده‌شدن کانال و دریافت پیام را به پل منتقل کنید و METRIX_TWA=true را به URL اجرای آن اضافه کنید. برای هر نشست مرورگر، پل جدیدی بسازید.

مقداردهی اولیه Web SDK در وب‌سایت

برای ادغام‌های جدید، از Web SDK نسخه 2.9.1 استفاده کنید و آن را مثل همیشه مقداردهی اولیه کنید. اگر صفحه با METRIX_TWA=true باز شده باشد، SDK خودش به SDK نیتیو متصل می‌شود. حالت TWA برای کل نشست مرورگر حفظ می‌شود، بنابراین ناوبری در همان تب نیازی به نگه‌داشتن این پارامتر ندارد.

import { init, newEvent, onNativeReady } from '@metrixorg/websdk'; init('APP_ID', 'API_KEY', { sessionTracking: { enabled: true }, // Used only for ordinary browser/PWA visits. }); onNativeReady() .then(transport => console.log(`Native SDK connected via ${transport}`)) // "twa" .catch(error => console.log('Native SDK unavailable:', error.message)); // Routed to the native SDK inside the TWA, and to the Web SDK elsewhere. newEvent('EVENT_SLUG', { source: 'web' });

onNativeReady() فقط پس از تکمیل handshake در اندروید مقدار "twa" را برمی‌گرداند (یا داخل WebView اندروید مقدار "webview"). اگر هیچ انتقال نیتیوی در دسترس نباشد یا مهلت handshake تمام شود reject می‌شود؛ fallback به مرورگر به‌عنوان آماده‌بودن نیتیو گزارش نمی‌شود. callback موفقیت رویدادها به معنای پذیرش توسط SDK نیتیو است، نه تحویل به سرور.

اگر اتصال نیتیو برقرار نشود، مقداردهی اولیه ادامه پیدا می‌کند و فراخوانی‌هایی که در زمان اتصال انجام شده‌اند از طریق Web SDK دوباره اجرا می‌شوند. پس از اتصال ناموفق، SDK تشخیص TWA را در صفحه‌های بعدی پس از دو دقیقه دوباره امتحان می‌کند. این رفتار را می‌توانید با گزینه‌های زیر در init تغییر دهید:

گزینهتوضیح
nativeOnlyردیابی مرورگر و fallback را غیرفعال می‌کند؛ فقط از انتقال نیتیو (TWA یا WebView) استفاده می‌شود.
twaOnlyردیابی مرورگر را غیرفعال می‌کند و فقط انتقال TWA را مجاز می‌داند.
nativeBridgeTimeoutMsمهلت handshake، از 1 تا 120000 میلی‌ثانیه. مقدار پیش‌فرض 10000 است.
init('APP_ID', 'API_KEY', { twaOnly: true, nativeBridgeTimeoutMs: 15000 });

تا زمانی که پل فعال است، اتریبیوشن و شناسه کاربر متریکس از SDK نیتیو می‌آیند. در این حالت، APIهای مخصوص وب زیر با خطای صریح reject می‌شوند: getAttributionStatus، onMetrixUserIdReceived، onAutomationUserIdReceived، subscribePush، openPushConfirmBackdrop، onPushStateResolved و getPushSubscription. همچنین notificationPermissionState مقدار undefined برمی‌گرداند. اتریبیوشن و شناسه کاربر را در اپلیکیشن اندروید بخوانید.

بررسی پیاده‌سازی

با اپ امضاشده و assetlinks.json منتشرشده، برنامه را در Chrome 115+ اجرا کنید و بررسی کنید وضعیت پل نیتیو READY شود و onNativeReady() مقدار "twa" را برگرداند. یک رویداد آزمایشی ارسال کنید و آن را در لاگ SDK اندروید یا داشبورد ببینید. به صفحه دیگری در همان تب بروید و بررسی کنید فراخوانی‌ها همچنان به SDK نیتیو می‌روند. در صورت قطع ارتباط، یکسان‌بودن مبدأ، پکیج و اثرانگشت، رابطه use_as_origin، نسخه مرورگر و وجود METRIX_TWA=true در URL اجرا را بررسی کنید. وب‌سایت باید در صورت دردسترس‌نبودن کانال نیتیو نیز کار کند.