راهنمای ادغام

آندره سیپریانی بندرا

راه‌اندازی یک فعالیت وب معتمد به برنامه‌نویسان نیازی به نوشتن کد جاوا ندارد، اما Android Studio لازم است. این راهنما با استفاده از Android Studio 3.3 ایجاد شده است. اسناد نحوه نصب آن را بررسی کنید.

یک پروژه فعالیت وب مورد اعتماد ایجاد کنید

هنگام استفاده از Trusted Web Activities، پروژه باید API 16 یا بالاتر را هدف قرار دهد.

Android Studio را باز کرده و روی Start a new Android Studio کلیک کنید.

Android Studio از شما می‌خواهد که یک نوع فعالیت را انتخاب کنید. از آنجایی که Trusted Web Activities از یک فعالیت ارائه شده توسط کتابخانه پشتیبانی استفاده می کند، Add No Activity را انتخاب کنید و روی Next کلیک کنید.

در مرحله بعد، ویزارد تنظیمات پروژه را درخواست می کند. در اینجا شرح مختصری از هر فیلد آورده شده است:

  • نام: نامی که برای برنامه شما در راه‌انداز Android استفاده می‌شود.
  • نام بسته: یک شناسه منحصر به فرد برای برنامه های Android در فروشگاه Play و در دستگاه های Android. برای اطلاعات بیشتر در مورد الزامات و بهترین روش‌ها برای ایجاد نام بسته برای برنامه‌های Android، اسناد را بررسی کنید.
  • ذخیره مکان: جایی که Android Studio پروژه را در سیستم فایل ایجاد می کند.
  • زبان: پروژه نیازی به نوشتن هیچ کد جاوا یا کاتلین ندارد. جاوا را به عنوان پیش فرض انتخاب کنید.
  • حداقل سطح API: کتابخانه پشتیبانی حداقل به سطح 16 API نیاز دارد. API 16 را یکی از نسخه های بالا انتخاب کنید.

چک باکس‌های باقیمانده را بدون علامت بگذارید، زیرا از برنامه‌های فوری یا مصنوعات AndroidX استفاده نمی‌کنیم، و روی Finish کلیک کنید.

کتابخانه پشتیبانی از فعالیت وب مورد اعتماد را دریافت کنید

برای راه اندازی کتابخانه Trusted Web Activity در پروژه، باید فایل ساخت Application را ویرایش کنید. به دنبال بخش Gradle Scripts در Project Navigator بگردید. دو فایل به نام build.gradle وجود دارد که ممکن است کمی گیج کننده باشد و توضیحات داخل پرانتز به شناسایی فایل صحیح کمک می کند.

فایلی که به دنبال آن هستیم فایلی است که ماژول ماژول در کنار نام آن قرار دارد.

کتابخانه Trusted Web Activities از ویژگی‌های Java 8 استفاده می‌کند و اولین تغییر جاوا 8 را فعال می‌کند. یک بخش compileOptions را به پایین بخش android اضافه کنید، مانند زیر:

android {
        ...
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
    }
}

مرحله بعدی کتابخانه پشتیبانی از فعالیت وب مورد اعتماد را به پروژه اضافه می کند. یک وابستگی جدید به بخش dependencies اضافه کنید:

dependencies {
    implementation 'com.google.androidbrowserhelper:androidbrowserhelper:2.2.0'
}

Android Studio درخواستی برای همگام سازی پروژه یک بار دیگر نشان می دهد. روی پیوند Sync Now کلیک کنید و آن را همگام کنید.

فعالیت وب مورد اعتماد را راه اندازی کنید

راه‌اندازی فعالیت وب مورد اعتماد با ویرایش مانیفست برنامه Android انجام می‌شود.

در Project Navigator ، بخش برنامه و به دنبال آن مانیفست ها را گسترش دهید و روی AndroidManifest.xml دوبار کلیک کنید تا فایل باز شود.

از آنجایی که از اندروید استودیو درخواست کردیم هنگام ایجاد پروژه ما هیچ فعالیتی را به آن اضافه نکند، مانیفست خالی است و فقط حاوی تگ برنامه است.

با درج یک تگ activity در تگ application ، فعالیت وب مورد اعتماد را اضافه کنید:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        tools:ignore="GoogleAppIndexingWarning">
        <activity
            android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">

           <!-- Edit android:value to change the url opened by the Trusted Web Activity -->
           <meta-data
               android:name="android.support.customtabs.trusted.DEFAULT_URL"
               android:value="https://airhorner.com" />

           <!-- This intent-filter adds the Trusted Web Activity to the Android Launcher -->
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>

           <!--
             This intent-filter allows the Trusted Web Activity to handle Intents to open
             airhorner.com.
           -->
           <intent-filter>
               <action android:name="android.intent.action.VIEW"/>
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE"/>

               <!-- Edit android:host to handle links to the target URL-->
               <data
                 android:scheme="https"
                 android:host="airhorner.com"/>
           </intent-filter>
        </activity>
    </application>
</manifest>

برچسب‌هایی که به XML اضافه می‌شوند، مانیفست استاندارد برنامه Android هستند. دو بخش از اطلاعات مرتبط برای زمینه فعالیت‌های وب مورد اعتماد وجود دارد:

  1. تگ meta-data به فعالیت وب مورد اعتماد می گوید که کدام URL را باید باز کند. ویژگی android:value با URL PWA که می خواهید باز کنید تغییر دهید. در این مثال، https://airhorner.com است.
  2. دومین تگ intent-filter به فعالیت وب مورد اعتماد اجازه می دهد تا Intent های Android را که https://airhorner.com را باز می کنند، رهگیری کند. ویژگی android:host داخل تگ data باید به دامنه ای که توسط Trusted Web Activity باز می شود اشاره کند.

بخش بعدی نحوه راه اندازی Digital AssetLinks را برای تأیید ارتباط بین وب سایت و برنامه و حذف نوار URL نشان می دهد.

نوار URL را بردارید

فعالیت‌های وب مورد اعتماد نیاز به ارتباط بین برنامه Android و وب‌سایت برای حذف نوار URL دارند.

این ارتباط از طریق پیوندهای دارایی دیجیتال ایجاد می شود و انجمن باید به هر دو صورت ایجاد شود، از برنامه به وب سایت و از وب سایت به برنامه پیوند داده شود.

برای اهداف اشکال‌زدایی، می‌توان برنامه را روی اعتبارسنجی وب‌سایت تنظیم کرد و Chrome را برای رد شدن از تأیید اعتبار وب‌سایت به برنامه راه‌اندازی کرد.

app > res > values > strings.xml را باز کنید و عبارت Digital AssetLinks را در زیر اضافه کنید:

<resources>
    <string name="app_name">AirHorner Trusted Web Activity</string>
    <string name="asset_statements">
        [{
            \"relation\": [\"delegate_permission/common.handle_all_urls\"],
            \"target\": {
                \"namespace\": \"web\",
                \"site\": \"https://airhorner.com\"}
        }]
    </string>
</resources>

محتویات ویژگی site را تغییر دهید تا با طرح و دامنه باز شده توسط «فعالیت وب معتمد» مطابقت داشته باشد.

بازگشت به فایل Manifest برنامه Android، AndroidManifest.xml ، با افزودن یک تگ meta-data جدید، به بیانیه پیوند دهید، اما این بار به عنوان فرزند تگ application :

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

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

        <activity>
            ...
        </activity>

    </application>
</manifest>

ما اکنون رابطه ای از برنامه اندروید با وب سایت برقرار کرده ایم. اشکال زدایی این بخش از رابطه بدون ایجاد اعتبارسنجی وب سایت برای برنامه مفید است.

در اینجا نحوه آزمایش این روی یک دستگاه توسعه آورده شده است:

حالت اشکال زدایی را فعال کنید

  1. Chrome را در دستگاه توسعه باز کنید، به chrome://flags بروید، موردی به نام Enable command line را در دستگاه‌های روت نشده جستجو کنید و آن را به ENABLED تغییر دهید و سپس مرورگر را مجدداً راه‌اندازی کنید.
  2. سپس در برنامه ترمینال سیستم عامل خود از Android Debug Bridge (نصب شده با Android Studio) استفاده کنید و دستور زیر را اجرا کنید:
adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://airhorner.com\"' > /data/local/tmp/chrome-command-line"

Chrome را ببندید و برنامه خود را از Android Studio دوباره راه اندازی کنید. اکنون برنامه باید به صورت تمام صفحه نشان داده شود.

دو بخش اطلاعاتی وجود دارد که توسعه‌دهنده باید از برنامه جمع‌آوری کند تا ارتباط ایجاد کند:

  • نام بسته: اولین اطلاعات نام بسته برنامه است. این همان نام بسته ای است که هنگام ایجاد برنامه ایجاد می شود. همچنین می‌توان آن را در داخل Module build.gradle ، در زیر Gradle Scripts > build.gradle (Module: app) یافت و مقدار مشخصه applicationId است.
  • اثر انگشت SHA-256: برنامه های اندروید باید امضا شده باشند تا در فروشگاه Play بارگذاری شوند. از همین امضا برای برقراری ارتباط بین وب سایت و برنامه از طریق اثر انگشت SHA-256 کلید آپلود استفاده می شود.

مستندات Android به طور مفصل نحوه تولید کلید با استفاده از Android Studio را توضیح می دهد . مطمئن شوید که مسیر ، نام مستعار و گذرواژه‌های فروشگاه کلید را یادداشت کنید، زیرا برای مرحله بعدی به آن نیاز خواهید داشت.

اثر انگشت SHA-256 را با استفاده از keytool با دستور زیر استخراج کنید:

keytool -list -v -keystore [path] -alias [alias] -storepass [password] -keypass [password]

مقدار اثر انگشت SHA-256 در بخش اثر انگشت گواهی چاپ می شود. در اینجا یک نمونه خروجی آورده شده است:

keytool -list -v -keystore ./mykeystore.ks -alias test -storepass password -keypass password

Alias name: key0
Creation date: 28 Jan 2019
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Issuer: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Serial number: ea67d3d
Valid from: Mon Jan 28 14:58:00 GMT 2019 until: Fri Jan 22 14:58:00 GMT 2044
Certificate fingerprints:
   SHA1: 38:03:D6:95:91:7C:9C:EE:4A:A0:58:43:A7:43:A5:D2:76:52:EF:9B
   SHA256: F5:08:9F:8A:D4:C8:4A:15:6D:0A:B1:3F:61:96:BE:C7:87:8C:DE:05:59:92:B2:A3:2D:05:05:A5:62:A5:2F:34
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3

با در دست داشتن هر دو اطلاعات، به مولد پیوندهای دارایی بروید، فیلدها را پر کنید و Generate Statement را بزنید. عبارت تولید شده را کپی کنید و آن را از دامنه خود، از URL /.well-known/assetlinks.json ارائه دهید.

ایجاد یک آیکون

هنگامی که Android Studio یک پروژه جدید ایجاد می کند، با یک نماد پیش فرض همراه خواهد بود. به عنوان یک توسعه دهنده، می خواهید نماد خود را ایجاد کنید و برنامه خود را از سایرین در لانچر Android متمایز کنید.

Android Studio حاوی Image Asset Studio است که ابزارهای لازم برای ایجاد نمادهای صحیح را برای هر وضوح و شکل مورد نیاز برنامه شما فراهم می کند.

در داخل Android Studio، به File > New > Image Asset بروید، Launcher Icons (Adaptative and Legacy) را انتخاب کنید و مراحل را از Wizard دنبال کنید. برای ایجاد یک نماد سفارشی برای برنامه

ایجاد یک APK امضا شده

با وجود فایل assetlinks در دامنه شما و تگ asset_statements پیکربندی شده در برنامه Android، مرحله بعدی ایجاد یک برنامه امضا شده است. باز هم، مراحل این امر به طور گسترده مستند شده است.

APK خروجی را می توان با استفاده از adb در دستگاه آزمایشی نصب کرد:

adb install app-release.apk

اگر مرحله راستی‌آزمایی با شکست مواجه شد، می‌توانید با استفاده از پل اشکال‌زدایی Android، از ترمینال سیستم‌عامل خود و با دستگاه تست متصل، پیام‌های خطا را بررسی کنید.

adb logcat | grep -e OriginVerifier -e digital_asset_links

با آپلود APK ایجاد شده، اکنون می توانید برنامه را در فروشگاه Play آپلود کنید .

اضافه کردن یک صفحه نمایش اسپلش

از Chrome 75 ، Trusted Web Activities از Splash Screens پشتیبانی می‌کند. Splash Screen را می توان با افزودن چند فایل تصویری جدید و پیکربندی به پروژه راه اندازی کرد.

مطمئن شوید که Chrome 75 یا بالاتر را به‌روزرسانی کرده‌اید و از آخرین نسخه کتابخانه پشتیبانی فعالیت وب معتمد استفاده کنید.

تولید تصاویر برای Splash Screen

دستگاه های اندرویدی می توانند اندازه صفحه نمایش و تراکم پیکسلی متفاوتی داشته باشند. برای اطمینان از اینکه Splash Screen در همه دستگاه ها خوب به نظر می رسد، باید تصویر را برای هر تراکم پیکسلی ایجاد کنید.

توضیح کامل پیکسل های مستقل از نمایشگر (dp یا dip) خارج از محدوده این مقاله است، اما یک مثال می تواند ایجاد تصویری با ابعاد 320x320dp باشد که نشان دهنده مربع 2x2 اینچ بر روی صفحه نمایش دستگاه با هر چگالی است. معادل 320x320 پیکسل در تراکم mdpi .

از آنجا می توانیم اندازه های مورد نیاز برای تراکم پیکسل های دیگر را استخراج کنیم. در زیر لیستی با تراکم پیکسل، ضریب اعمال شده در اندازه پایه (320x320dp)، اندازه حاصل به پیکسل و مکانی که تصویر باید در پروژه Android Studio اضافه شود، آمده است.

تراکم ضرب کننده اندازه محل پروژه
mdpi (خط پایه) 1.0x 320x320 پیکسل /res/drawable-mdpi/
ldpi 0.75x 240x240 پیکسل /res/drawable-ldpi/
hdpi 1.5 برابر 480x480 پیکسل /res/drawable-hdpi/
xhdpi 2.0x 640x640 پیکسل /res/drawable-xhdpi/
xxhdpi 3.0x 960x960 پیکسل /res/drawable-xxhdpi/
xxxhdpi 4.0x 1280x1280 پیکسل /res/drawable-xxxhdpi/

به روز رسانی اپلیکیشن

با ایجاد تصاویر مربوط به صفحه اسپلش، زمان آن رسیده است که تنظیمات لازم را به پروژه اضافه کنید.

ابتدا یک ارائه دهنده محتوا به مانیفست اندروید ( AndroidManifest.xml ) اضافه کنید.

<application>
    ...
    <provider
        android:name="androidx.core.content.FileProvider"
        android:authorities="com.example.twa.myapplication.fileprovider"
        android:grantUriPermissions="true"
        android:exported="false">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/filepaths" />
    </provider>
</application>

سپس، منبع res/xml/filepaths.xml را اضافه کنید و مسیر صفحه نمایش twa splash را مشخص کنید:

<paths>
    <files-path path="twa_splash/" name="twa_splash" />
</paths>

در نهایت، meta-tags به مانیفست اندروید اضافه کنید تا LauncherActivity را سفارشی کنید:

<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">
    ...
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_IMAGE_DRAWABLE"
               android:resource="@drawable/splash"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_BACKGROUND_COLOR"
               android:resource="@color/colorPrimary"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_FADE_OUT_DURATION"
               android:value="300"/>
    <meta-data android:name="android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY"
               android:value="com.example.twa.myapplication.fileprovider"/>
    ...
</activity>

مطمئن شوید که مقدار تگ android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY با مقدار تعریف شده از ویژگی android:authorities در داخل تگ provider مطابقت دارد.

شفاف کردن LauncherActivity

علاوه بر این، با تنظیم یک تم شفاف برای LauncherActivity، مطمئن شوید که LauncherActivity شفاف است تا از نمایش یک صفحه سفید قبل از پخش شدن آب جلوگیری کنید:

<application>
    ...
    <activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
              android:theme="@android:style/Theme.Translucent.NoTitleBar">
    ...
    </activity>
</application>

ما مشتاقانه منتظریم تا ببینیم توسعه‌دهندگان با فعالیت‌های وب مورد اعتماد چه می‌سازند. برای ارسال بازخورد، با ما در @ChromiumDev تماس بگیرید.