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

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>

تعديل عنوان 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>

الخاتمة

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

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

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

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