تمرير المعلومات إلى نشاط ويب موثوق به باستخدام مَعلمات طلب البحث

André Cipriani Bandarra

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

وتشمل حالات الاستخدام الشائعة لهذا الإجراء تنفيذ شرائح إحصاءات مخصّصة لقياس عمليات التثبيت والجلسات التي بدأت من "نشاط الويب الموثوق به". يمكن إضافة مَعلمات طلب البحث إلى عنوان URL لبدء التطبيق لتنفيذ ذلك.

تعديل عنوان URL لصفحة البداية

إذا كانت المَعلمة التي يتم تمريرها إلى تطبيق الويب التقدّمي ستظلّ كما هي لجميع المستخدمين وعمليات الإطلاق، يمكن إلحاق المَعلمة مباشرةً بعنوان URL لبدء التشغيل. على سبيل المثال، يتم استخدام هذه البيانات عندما يريد المطوّرون قياس عدد جلسات التنقّل التي تم إنشاؤها من "نشاط ويب موثوق".

استخدام Bubblewrap

Bubblewrap هي أداة تم إنشاؤها لمساعدة المطوّرين على إنشاء مشروع لتطبيق Android يشغّل تطبيقات ويب تقدّمية حالية باستخدام نشاط موثوق به على الويب. يحتوي على مكتبة وواجهة سطر أوامر.

إنشاء مشروع جديد

عند استخدام واجهة سطر أوامر Bubblewrap، يتمّ إعداد مشروع باستخدام الأمر init، وإنشاء قيم تلقائية من ملف بيان الويب المقدَّم كمَعلمة:

bubblewrap init --manifest https://material.money/manifest.json

سيستخدم المعالج start_url من ملف بيان الويب بشكل تلقائي وسيطلب من المستخدمين تأكيد القيمة، ما يمنح المطوّرين فرصة إضافة مَعلمات إضافية إلى عنوان URL المستخدَم لبدء تطبيق الويب التفاعلي.

تعديل مشروع حالي

عند إنشاء Bubblewrap لمشروع، يتم تخزين معلومات هذا المشروع المحدّد في ملف يُسمى twa-manifest.json في مجلد المشروع. لتعديل عنوان URL لبدء مشروع حالي، على المطوّرين تعديل الملف:

{
  ...
  "startUrl": "/?utm_source=trusted-web-activity",
  ...
}

بعد ذلك، عليك إعادة إنشاء ملفات المشروع وتطبيق عنوان URL الجديد لصفحة البداية.

bubblewrap update

استخدام "استوديو Android"

عند استخدام Android Studio وLauncherActivity التلقائي، يتم تعريف startUrl كعلامة وصفية داخل AndroidManifest.xml، ويمكننا تغيير عنوان URL المستخدَم لبدء "نشاط الويب الموثوق به" من خلال تعديله:

<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
    android:label="@string/app_name">
    ...
    <meta-data android:name="android.support.customtabs.trusted.DEFAULT_URL"
        android:value="https://svgomg.firebaseapp.com/?utm_source=trusted-web-activity" />
    ...
</activity>

ملاحظة: تتولى أداة Bubblewrap ضمان تطابق عناوين URL في التطبيق مع المصدر نفسه، وبالتالي، تستخدم عنوان URL نسبيًا لعنوان URL المبدئي. عند تعديل ملف AndroidManifest.xml، يجب استخدام عنوان URL بالكامل، بما في ذلك المخطط والنطاق.

تعديل عنوان URL لنقطة البداية ديناميكيًا

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

الخطوة 1: إنشاء نشاط LauncherActivity مخصّص

public class CustomQueryStringLauncherActivity extends LauncherActivity {
    private String getDynamicParameterValue() {
        return String.valueOf((int)(Math.random() * 1000));
    }

    @Override
    protected Uri getLaunchingUrl() {
        // Get the original launch Url.
        Uri uri = super.getLaunchingUrl();

        // Get the value we want to use for the parameter value
        String customParameterValue = getDynamicParameterValue();

        // Append the extra parameter to the launch Url
        return uri
                .buildUpon()
                .appendQueryParameter("my_parameter", customParameterValue)
                .build();
    }
}

الخطوة 2: تعديل AndroidManifest.xml لاستخدام LauncherActivity المخصّص

<activity android:name="com.myapp.CustomQueryStringLauncherActivity"
    android:label="@string/app_name">
    ...
    <meta-data android:name="android.support.customtabs.trusted.DEFAULT_URL"
        android:value="https://squoosh.app/?utm_source=trusted-web-activity" />
    ...
</activity>

ملاحظة: لا تتيح أداة Bubblewrap إنشاء مَعلمات طلب بحث ديناميكيًا في الوقت الحالي. يهمّنا معرفة رأي المطوّرين الذين يحتاجون إلى هذه الميزة. يمكنك الاطّلاع على Bubblewrap أداة تتبُّع المشاكل وإخبارنا بحالة الاستخدام.

الخاتمة

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

على المطوّرين معرفة هذه الآثار، ويمكنهم التخفيف منها باستخدام link rel=noreferrer أو تنظيف عنوان URL باستخدام Page Location API.

لا يقدّم بروتوكول "النشاط الموثوق به على الويب" حاليًا آلية لتبادل الرسائل مع الجزء الأصلي من التطبيق بعد استدعاء جزء الويب.

نعتقد أنّ واجهات برمجة تطبيقات Web Platform الحالية أو القادمة تتيح معظم حالات الاستخدام التي يحتاجها المطوّرون. إذا كنت تبحث عن واجهات برمجة تطبيقات ويب جديدة أو قادمة، يمكنك الاطّلاع على صفحة حالة الإمكانات الجديدة.