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

André Cipriani Bandarra

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

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

تعديل عنوان URL للبدء

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

استخدام فقاعة المحادثة

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

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

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

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

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

عرض مُخرج سطر الأوامر

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

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

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

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

bubblewrap update

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

عند استخدام "استوديو Android" ومشغّل التطبيقات التلقائي، يتم تحديد عنوان URL للبدء كعلامة وصفية داخل ملف 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: إنشاء نشاط مشغّل تطبيقات مخصّص

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 لاستخدام "نشاط مشغّل التطبيقات المخصّص"

<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 API الحالية أو القادمة تتيح معظم حالات الاستخدام التي يحتاجها المطوّرون. إذا كنت تبحث عن واجهات برمجة تطبيقات ويب جديدة أو قادمة، يُرجى الاطّلاع على صفحة حالة الإمكانيات الجديدة.