استقبال تطبيقات الويب التقدمية البيانات المشاركة عبر الواجهة البرمجية Web Share Target

5 مايو 2022

https://academy.hsoub.com/programming/general/%D8%A7%D8%B3%D8%AA%D9%82%D8%A8%D8%A7%D9%84-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D8%A7%D9%84%D9%88%D9%8A%D8%A8-%D8%A7%D9%84%D8%AA%D9%82%D8%AF%D9%85%D9%8A%D8%A9-%D8%A7%D9%84%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B4%D8%A7%D8%B1%D9%83%D8%A9-%D8%B9%D8%A8%D8%B1-%D8%A7%D9%84%D9%88%D8%A7%D8%AC%D9%87%D8%A9-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D9%8A%D8%A9-web-share-target-r1544/

متابعون 1

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

كان فقط بإمكان التطبيقات المثبتة على نظام التشغيل platform-specific التسجيل في نظام التشغيل لاستقبال البيانات المشاركة من التطبيقات المثبتة الأخرى، لكن باستخدام الواجهة البرمجية Web Share Target (وُجهة مشاركة الويب) التي تعمل في الخلفية Web share Target API، أصبح بإمكان تطبيقات الويب المثبتة على الجهاز أيضًا التسجيل مع نظام التشغيل كهدف مشاركة لاستقبال بيانات من التطبيقات الأخرى.

إمكانية استقبال تطبيقات الويب البيانات المُشاركة يُعد مكمّلًا لإمكانية تطبيقات أخرى على مشاركة البيانات، يمكنك مراجعة مقال مشاركة البيانات عبر الواجهة Web Share في تطبيقات الويب التقدمية.

تجريب الواجهة البرمجية Web Share Target

إن أردت تجريب الواجهة البرمجة Web Share Target، اتبع الخطوات التالية:

افتح العرض التوضيحي لهذه الواجهة Web Share Target Demo وذلك على متصفح Chrome، بالإصدار 76 فما فوق على نظام أندرويد، أو 89 فما فوق على سطح المكتب.
انقر زر المشاركة في العرض التوضيحي.
اختر أحد التطبيقات الظاهرة في مُنتقي جهات المشاركة كوجْهة للمشاركة.

بعد إتمامك عملية المُشاركة، ستُشاهد النص المُشارَك في التطبيق الذي اخترته.

منتقي وجهة المشاركة على مستوى النظام.

تسجيل التطبيق كهدف مشاركة

يجب أن يستوفي تطبيقك معايير Chrome الخاصة بقابلية تثبيت التطبيقات لتسجيله كوجهة مشاركة، أيضًا حتى يتمكن المستخدم من مشاركة محتوى ما إلى تطبيقك، فيجب أن يكون تطبيقك مثبتًا في شاشته الرئيسية، فهذا يمنع المواقع من إضافة نفسها عشوائيًا إلى منتقي وُجهات المشاركة Share Target Picker المتاح للمستخدم مشاركة المحتوى إليها.

حدِّث ملف بيان موارد تطبيق الويب

لتسجيل تطبيقك كهدف مشاركة، أضف الخاصية share_target إلى ملف بيانه manifest، فهي تخبر نظام التشغيل بتضمين تطبيقك كخيار في منتقي وُجْهات المشاركة، وبشكل عام ما تضيفه إلى الخاصية share_target يضبط البيانات التي سيقبل تطبيقك أن تشارُكها.

هناك ثلاثة طرق شائعة لضبط الخاصية share_target:

قبول محتوى المشاركة الأساسي.
قبول بيانات مشاركة تُحْدِث تغييرات في التطبيق.
قبول تشارُك الملفات.

قبول محتوى المشاركة الأساسي

إذا أردت لتطبيقك المحدد كوُجْهة مشاركة أن يقبل فقط محتوى المشاركة الأساسي مثل البيانات والروابط والنصوص، فأضف ما يلي إلى ملف بيانه manifest.json:

"share_target": {
  "action": "/share-target/",
  "method": "GET",
  "params": {
    "title": "title",
    "text": "text",
    "url": "url"
  }
}

إذا كان تطبيقك يتيح المشاركة بواسطة بروتوكول عنوان URL Scheme، وكان يستخدم القيمة body للحقل text بدلاً من القيمة text، يمكنك استبدال text": "text"‎" في الشيفرة السابقة بالقيمة "text": "body".

النوع الافتراضي لنوع طلبية http والمعبر عنه بالحقل method هو "GET". يشير حقل enctype غير الظاهر في الشيفرة السابقة إلى نوع تشفير البيانات، يعيَّن هذا الحقل بالقيمة "application / x-www-form-urlencoded" افتراضيًا عندما تكون الطريقة هي "GET".

قبول بيانات مشاركة تُحْدِث تغييرات في التطبيق

إذا كانت البيانات المشاركة تُحدِثْ تغييرات في التطبيق الوجْهة بطريقة ما، مثلًا تحفظ إشارات مرجعية فيه، وقتها عيّن الحقل method بالنوع "POST" واضبط الحقل enctype.

يُنشئ المثال التالي إشارة مرجعية في التطبيق الوُجْهة، لذا فإنه يستخدم "POST" للحقل method و القيمة "multart/form-data" للحقل enctype:

{
  "name": "Bookmark",
  "share_target": {
    "action": "/bookmark",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "url": "link"
    }
  }
}

قبول مشاركة الملفات

كما هو الحال مع البيانات المُشاركة التي تُحْدِث تغييرات في التطبيق، يتطلب قبول مشاركة الملفات أن تكون طريقة المشاركة method هي "POST" وأن يكون نوع enctype هو "multipart/form-data"، ويجب إضافة الحقل files، التي تمثل مصفوفة أنواع الملفات التي يقبلها تطبيقك، عناصر المصفوفة عبارة عن كائنات مكونة من حقلين: name وaccept. يمثل حقل accept نوع MIME للملف أو إمتداده أو مصفوفة تحتوي كليهما. يفضّل توفير مصفوفة تتضمن كلاً من نوع MIME وامتداد الملف لاختلاف أنظمة التشغيل في ما تفضِّل منهما.

{
  "name": "Aggregator",
  "share_target": {
    "action": "/cgi-bin/aggregate",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "name",
      "text": "description",
      "url": "link",
      "files": [
        {
          "name": "records",
          "accept": ["text/csv", ".csv"]
        },
        {
          "name": "graphs",
          "accept": "image/svg+xml"
        }
      ]
    }
  }
}

معالجة المحتوى المشارك

طريقة التعامل مع البيانات المُشارَكة أمر متروك لك ويعتمد على تطبيقك، مثلًا:

يمكن لتطبيق البريد الإلكتروني، صياغة بريد إلكتروني جديد من المحتوى المشارَك، باستخدام العنوان title كموضوع للبريد الإلكتروني، والنص المُشارك text والرابط url متسلسلَين معًا كجسم لرسالة البريد.
يمكن لتطبيق تواصل إجتماعي صياغة منشور جديد من المحتوى المشارَك، بتجاهل العنوان title، والاستفادة من text كنص للمنشور، وإضافة url كرابط للمنشور أو حتى كنص أساسي وذلك إذا كان text مفقود، وإذا كان url مفقودًا، فقد يفحص التطبيق النص text بحثًا عن أي عنوان URL ويضيفه كرابط.
يمكن لتطبيق مشاركة الصور إنشاء عرض شرائح جديد من المحتوى المشارَك، باستخدام العنوان title كعنوان لعرض الشرائح و النص text كوصف للعرض والملفات files (ملفات الصور) كشرائح تتحرك في العرض.
يمكن لتطبيق الرسائل النصية صياغة رسالة جديدة من المحتوى المشارَك وذلك باستخدام النص text وurl متسلسلَين معًا كنص للرسالة وتجاهل العنوان title.

معالجة مشاركات GET

إذا اختار المستخدم تطبيقك كوُجْهة مشاركة، وكانت طريقة المشاركة method في تطبيقك هي "GET" (الافتراضية)، يفتح المتصفح نافذة جديدة على عنوان URL بقيمة الحقل action ضمن الخاصية share_target، ويولِّد المتصفح بعدها استعلامًا نصيًا بسيطًا، مثلًا إذا كان التطبيق المشارِك يوفر عنوان title ونص text بقيم معينة، فإن سلسلة الاستعلام التي يولّدها المتصفح ستكون ?title=hello&text=world. ولمعالجة هذا الاستعلام، استخدم مستمع الحدث DOMContentLoaded (يحصل هذا الحدث عند الانتهاء من تحميل المستند وبناء DOM) في الواجهة الأمامية foreground وحلِّل نص الاستعلام:

window.addEventListener('DOMContentLoaded', () => {
  const parsedUrl = new URL(window.location);
  // searchParams.get() will properly handle decoding the values.
  console.log('Title shared: ' + parsedUrl.searchParams.get('title'));
  console.log('Text shared: ' + parsedUrl.searchParams.get('text'));
  console.log('URL shared: ' + parsedUrl.searchParams.get('url'));
});

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

يمكن أن تساعدك الأداة Workbox في تنفيذ تخزين مؤقت مسبق preaching بالاستفادة من عامل خدمة تطبيقك.

معالجة مشاركات POST

إذا كانت طريقة المشاركة method في تطبيقك هي "POST"، أي كان تطبيقك يقبل بيانات مُشاركة تُحْدِث تغييرات فيه أو يقبل تشارُك ملفات، فسيحتوي جسم طلب POST الوارد على البيانات التي مرَّرها التطبيق المُشارِك، والمشفرة باستخدام قيمة enctype المعيّنة في ملف البيان.

لا يمكن للواجهة الأمامية معالجة هذه البيانات مباشرة، بل تعاملها كطلب تمرره إلى عامل خدمة تطبيقك، الذي بواسطته يمكنك اعتراضها ومعالجتها باستخدام مستمع الحدث fetch.

self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  // If this is an incoming POST request for the
  // registered "action" URL, respond to it.
  if (event.request.method === 'POST' &&
      url.pathname === '/bookmark') {
    event.respondWith((async () => {
      const formData = await event.request.formData();
      const link = formData.get('link') || '';
      const responseUrl = await saveBookmark(link);
      return Response.redirect(responseUrl, 303);
    })());
  }
});

التحقق من المحتوى المُشارَك

تحقق من معالجة البيانات المُشاركة، فللأسف ليس هناك ما يضمن أن التطبيقات الوجهة ستشارك المحتوى المخصص في المكان المناسب بناء على معاملاته (معاملات المحتوى المشارك).

مثلًا يبقى حقل الرابط url فارغًا في نظام Android كما ترى في الصورة التالية، كونه غير مدعوم في نظام مشاركة Android، فغالبًا ما تظهر عناوين URL في حقل النص، أو أحيانًا في حقل العنوان.