أنشطة الويب الموثوقة الأولى بلا اتصال بالإنترنت

Demián Renzulli

في المرة الأولى التي يشغّل فيها المستخدم "تطبيق ويب تقدّمي" (PWA) من خلال "نشاط الويب الموثوق به"، لن يكون مشغّل الخدمة متاحًا بعد لأنّ عملية التسجيل لم تكتمل بعد. بالإضافة إلى ذلك، إذا لم يكن لدى المستخدم اتصال بالإنترنت أثناء بدء استخدام التطبيق، تتم إظهار صفحة خطأ الشبكة بدلاً من تجربة الاستخدام بلا إنترنت المخصّصة.

قد يحدث مثال على هذا السيناريو بعد تنزيل المستخدم لتطبيق PWA من "متجر Play". إذا لم يكن لدى المستخدم اتصال بالإنترنت عند محاولة فتح التطبيق لأول مرة، لن يكون عامل الخدمة متاحًا بعد لعرض صفحة النسخ الاحتياطي بلا إنترنت. سيتم عرض صفحة الخطأ العادية، مما يؤدي إلى تجربة سيئة.

يوضّح هذا الدليل كيفية عرض نشاطك في هذه الحالة من خلال التحقّق من حالة الشبكة قبل إطلاق ميزة "النشاط الموثوق على الويب".

إنشاء نشاط LauncherActivity مخصّص

الخطوة الأولى هي إنشاء نشاط مشغّل مخصّص. هذا Activity الذي سيحتوي على شاشة "غير متصل بالإنترنت" للإشارة إلى عدم توفّر اتصال بالإنترنت في المرة الأولى التي يفتح فيها المستخدم التطبيق.

استخدِم النشاط OfflineFirstTWALauncherActivity واجعل الإضافة: com.google.androidbrowserhelper.trusted.LauncherActivity.

import com.google.androidbrowserhelper.trusted.LauncherActivity;

public class OfflineFirstTWALauncherActivity extends LauncherActivity {

}

بعد ذلك، سجِّل النشاط في AndroidManifest.xml:

<activity android:name=".OfflineFirstTWALauncherActivity" android:theme="@style/Theme.Design.NoActionBar">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <!-- 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.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:host="airhorner.com" android:scheme="https" />
    </intent-filter>
</activity>

يسجِّل الرمز السابق OfflineFirstTWALauncherActivity كنشاط لانطلاق التطبيقات ويحدِّد https://airhorner.com كعنوان URL لفتحه عند إطلاق تطبيق TWA.

التعامل مع سيناريوهات عدم الاتصال بالإنترنت

أولاً، داخل النشاط، يمكنك إلغاء طريقة shouldLaunchImmediately() و جعلها تعرض false، لكي لا يتم تشغيل "النشاط الموثوق به على الويب" على الفور. يمكنك أيضًا إضافة عمليات تحقّق إضافية قبل الإطلاق الأوّلي:

@Override
protected boolean shouldLaunchImmediately() {
    // launchImmediately() returns `false` so we can check connection
    // and then render a fallback page or launch the Trusted Web Activity with `launchTwa()`.
    return false;
}

يمكنك إلغاء طريقة onCreate() للتحقّق من حالة الشبكة قبل بدء TWA. أضِف طلبًا إلى tryLaunchTwa()، وهي طريقة مساعدة ستحتوي على المنطق التالي:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    tryLaunchTwa();
}

بعد ذلك، نفِّذ tryLaunchTwa():

private void tryLaunchTwa() {
    // If TWA has already launched successfully, launch TWA immediately.
    // Otherwise, check connection status. If online, launch the Trusted Web Activity with `launchTwa()`.
    // Otherwise, if offline, render the offline fallback screen.
    if (hasTwaLaunchedSuccessfully()) {
        launchTwa();
    } else if (isOnline()) {
        firstTimeLaunchTwa();
    } else {
        renderOfflineFallback();
    }
}

تعالج التعليمة البرمجية السابقة ثلاثة سيناريوهات:

• إذا سبق تشغيل تطبيق TWA، سيتم تسجيل worker الخدمة، وسيكون بإمكان تطبيق الويب المتوافق مع الأجهزة الجوّالة الاستجابة بلا اتصال بالإنترنت. في هذه الحالة، اتصل بالعنصر launchTwa()، المحدّد في الفئة الرئيسية، لبدء نشاط الويب الموثوق به مباشرةً.
• إذا لم يتم تشغيل "النشاط الموثوق به على الويب" من قبل وكان المستخدم متصلاً بالإنترنت، يمكنك تشغيل "النشاط الموثوق به على الويب" للمرة الأولى باستخدام firstTimeLaunchTwa() الطريقة التي ستنفذها لاحقًا.
• إذا لم يتم تشغيل TWA وكان المستخدم غير متصل بالإنترنت، يجب عرض الشاشة البديلة المتوافقة مع الأجهزة المزوّدة بنظام التشغيل Android بلا اتصال بالإنترنت.

تنفيذ طرق المساعدة

الخطوة الأخيرة هي تنفيذ طرق المساعدة التي يستدعيها الرمز السابق. إليك الرمز للتحقّق من حالة "بلا إنترنت" isOnline():

private boolean isOnline() {
    ConnectivityManager connectivityManager = (ConnectivityManager) getSystemService(Context.CONNECTIVITY_SERVICE);
    NetworkInfo activeNetworkInfo = connectivityManager.getActiveNetworkInfo();
    return activeNetworkInfo != null && activeNetworkInfo.isConnected();
}

بعد ذلك، نفِّذ hasTwaLaunchedSuccessfully() الذي يتحقّق مما إذا كان قد تم إطلاق TWA مرة واحدة على الأقل:

private boolean hasTwaLaunchedSuccessfully() {
    // Return `true` if the preference "twa_launched_successfully" has already been set.
    SharedPreferences sharedPref = getSharedPreferences(getString(R.string.twa_offline_first_preferences_file_key), Context.MODE_PRIVATE);
    return sharedPref.getBoolean(getString(R.string.twa_launched_successfully), false);
}

يستدعي الرمز البرمجي السابق launchTWA() من الفئة الرئيسية، ويحفظ العلامة twa_launched_successfully في الإعدادات المفضّلة المشتركة. يشير ذلك إلى أنّه تم إطلاق TWA بنجاح مرة واحدة على الأقل.

تعرِض طريقة المساعدة المتبقية، renderOfflineFallback()، شاشة Android بلا اتصال بالإنترنت.

private void renderOfflineFallback() {
    setContentView(R.layout.activity_offline_first_twa);

    Button retryBtn = this.findViewById(R.id.retry_btn);
    retryBtn.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            // Check connection status. If online, launch the Trusted Web Activity for the first time.
            if (isOnline()) firstTimeLaunchTwa();
        }
    });
}

في هذا العرض التقديمي، حدّدنا تنسيق activity_offline_first_twa الذي يحتوي على زر لإعادة المحاولة، والذي سيؤدي في الوقت المناسب إلى تنفيذ firstTimeLaunchTwa() بعد التحقّق من الاتصال.

الخاتمة

• في المرة الأولى التي يشغّل فيها المستخدم تطبيق ويب تقدّمي (PWA) من خلال "نشاط الويب الموثوق فيه"، لن يكون مشغّل الخدمات متاحًا بعد.
• لتجنُّب عرض شاشة الوضع بلا إنترنت العادية إذا لم يكن لدى المستخدم اتصال بالإنترنت، يمكنك رصد حالة عدم الاتصال بالإنترنت وعرض شاشة احتياطية بلا إنترنت بدلاً من ذلك.
• لقد تعرّفت في هذا الدليل على كيفية تنفيذ هذه الاستراتيجية. إذا أردت الاطّلاع على الرمز الذي استخدمناه في هذا الدليل، يمكنك العثور على الحلّ الكامل في الإصدار التجريبي من واجهة برمجة التطبيقات للملفّات بلا إنترنت.