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

Demián Renzulli

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

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

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

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

إنشاء نشاط مُشغِّل تطبيقات مخصّص

الخطوة الأولى هي إنشاء نشاط مشغّل تطبيقات مخصّص. سيحتوي جهاز "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، يعني ذلك أنّه تم تسجيل مشغّل الخدمة، وسيتمكّن تطبيق الويب التقدّمي من الاستجابة بلا اتصال بالإنترنت. في هذه الحالة، اطلب launchTwa()، المحدد في الفئة الرئيسية، لتشغيل نشاط الويب الموثوق به مباشرةً.
• إذا لم يتم إطلاق تطبيق الويب التقدّمي (TWA) من قبل وكان المستخدم متصلاً بالإنترنت، شغِّل نشاط الويب الموثوق به لأول مرة باستخدام طريقة firstTimeLaunchTwa() التي ستنفّذها لاحقًا.
• إذا لم يكن قد تم تشغيل TWA بعد وكان المستخدم غير متصل بالإنترنت، يمكنك عرض الشاشة الاحتياطية الأصلية بلا إنترنت.

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

الخطوة الأخيرة هي تنفيذ طرق المساعدة التي تم استدعاءها بواسطة التعليمة البرمجية السابقة. إليك رمز التحقّق من حالة عدم الاتصال بالإنترنت 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) من خلال نشاط موثوق على الويب، لن يكون مشغّل الخدمات متاحًا بعد.
• لتجنُّب عرض الشاشة العادية بلا اتصال بالإنترنت إذا لم يكن لدى المستخدم اتصال بالإنترنت، يمكنك رصد حالة عدم الاتصال بالإنترنت وعرض شاشة احتياطية بلا اتصال بالإنترنت بدلاً من ذلك.
• تعلمت في هذا الدليل كيفية تنفيذ هذه الإستراتيجية. إذا كنت مهتمًا بالتحقق من الرمز الذي استخدمناه في هذا الدليل، يمكنك العثور على الحل الكامل في العرض التوضيحي لأول TWA بلا اتصال بالإنترنت.