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 اجرا را بررسی کنید.
وبسایت باید در صورت دردسترسنبودن کانال نیتیو نیز کار کند.