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

المشاركة على الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي بشكل مبسّط باستخدام Web Share Target API

Pete LePage

Joe Medley

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

في الماضي، كان بإمكان التطبيقات الخاصة بالنظام الأساسي فقط التسجيل في نظام التشغيل لتلقي مشاركات من تطبيقات أخرى مثبَّتة. أمّا باستخدام Web Share API، فيمكن لتطبيقات الويب المثبّتة التسجيل في نظام التشغيل الأساسي كهدف للمشاركة لتلقّي المحتوى المشترَك.

ملاحظة: تُعدّ Web Share Target API نصف الميزات الرائعة فقط. يمكن لتطبيقات الويب مشاركة البيانات أو الملفات أو الروابط أو النصوص باستخدام Web Share API. يمكنك الاطّلاع على Web Share API لمعرفة التفاصيل.

أداة اختيار هدف المشاركة على مستوى النظام مع تطبيق ويب تقدّمي (PWA) مثبَّت كخيار.

الاطّلاع على طريقة عمل هدف المشاركة على الويب

1. باستخدام الإصدار 76 من Chrome أو إصدار أحدث لنظام التشغيل Android أو الإصدار 89 من Chrome أو إصدار أحدث على جهاز كمبيوتر سطح المكتب، افتح العرض التوضيحي للاستهداف على الويب.
2. انقر على تثبيت لإضافة التطبيق إلى شاشتك الرئيسية أو استخدِم قائمة Chrome لإضافته إلى الشاشة الرئيسية عندما يُطلب منك ذلك.
3. افتح أي تطبيق يدعم المشاركة، أو استخدم زر المشاركة في التطبيق التجريبي.
4. من أداة اختيار الأهداف، اختَر اختبار المشاركة على الويب.

بعد المشاركة، من المفترض أن تظهر لك جميع المعلومات التي تمت مشاركتها في تطبيق الويب المستهدف للمشاركة على الويب.

تسجيل تطبيقك كهدف مستهدَف

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

تعديل بيان تطبيق الويب

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

• قبول المعلومات الأساسية
• يتم قبول تغييرات التطبيق
• جارٍ قبول الملفات

ملاحظة: يمكنك استخدام share_target واحدة فقط لكل بيان. وإذا أردت مشاركة المجلد مع أماكن مختلفة داخل تطبيقك، يمكنك إدراجه كخيار على الصفحة المقصودة للمشاركة (أي الصفحة التي يحدّدها إدخال url).

قبول المعلومات الأساسية

إذا كان تطبيقك المستهدَف لا يقبل سوى المعلومات الأساسية مثل البيانات والروابط والنص، أضِف ما يلي إلى ملف manifest.json:

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

إذا كان تطبيقك يحتوي حاليًا على نظام لمشاركة عنوان URL، يمكنك استبدال قيم params بمعلَمات طلب البحث الحالية. على سبيل المثال، إذا كان مخطط مشاركة عنوان URL يستخدم body بدلاً من text، يمكنك استبدال "text": "text" بـ "text": "body".

ويتم ضبط القيمة method تلقائيًا على "GET" إذا لم يتم تقديمها. يشير الحقل enctype، الذي لا يظهر في هذا المثال، إلى نوع الترميز للبيانات. بالنسبة إلى طريقة "GET"، يتم ضبط enctype تلقائيًا على "application/x-www-form-urlencoded" ويتم تجاهله في حال ضبطه على أي خيار آخر.

يتم قبول تغييرات التطبيق

إذا أدّت البيانات التي تمت مشاركتها إلى تغيير التطبيق المستهدَف بطريقة ما، مثلاً حفظ إشارة مرجعية في التطبيق المستهدَف، يمكنك ضبط قيمة method على "POST" وتضمين الحقل enctype. ينشئ المثال أدناه إشارة مرجعية في التطبيق المستهدَف، بحيث يستخدم "POST" في method و"multipart/form-data" لـ enctype:

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

جارٍ قبول الملفات

كما هي الحال مع تغييرات التطبيق، يتطلّب قبول الملفات أن تكون السمة method هي "POST" وأن تكون السمة enctype متوفّرة. بالإضافة إلى ذلك، يجب أن تكون السمة enctype "multipart/form-data"، ويجب إضافة إدخال files.

عليك أيضًا إضافة مصفوفة 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 في نص الرسالة أيضًا. في حال عدم توفّر السمة url، قد يفحص التطبيق text بحثًا عن عنوان URL ويضيفه كرابط.
• يمكن لتطبيق مشاركة الصور إنشاء عرض شرائح جديد باستخدام title كعنوان لعرض الشرائح، وtext كوصف، وfiles كصور عرض الشرائح.
• ويمكن لتطبيق مراسلة نصية صياغة رسالة جديدة باستخدام text وurl التسلسلية معًا وحذف title.

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

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

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 هي أداة يمكن أن تساعدك في تنفيذ التخزين المؤقت في مشغّل الخدمات.

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

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

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

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);
    })());
  }
});

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

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

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

على سبيل المثال، على Android، يكون الحقل url فارغًا لأنّه غير متاح في نظام المشاركة على Android. بدلاً من ذلك، ستظهر عناوين URL غالبًا في الحقل text، أو من حين لآخر في الحقل title.

المتصفحات المتوافقة

تتوفّر "واجهة برمجة التطبيقات المستهدفة لمشاركة الويب" كما هو موضّح أدناه:

على جميع الأنظمة الأساسية، يجب تثبيت تطبيق الويب قبل أن يظهر كهدف محتمل لتلقّي البيانات التي تتم مشاركتها.

نماذج التطبيقات

• السكواش
• تطبيق الويب التقدّمي لسجل القصاصات

إظهار الدعم لواجهة برمجة التطبيقات

هل تخطّط لاستخدام واجهة برمجة التطبيقات Web Share Target؟ يساعد الدعم العام فريق Chromium في تحديد أولويات الميزات ويعرض لمورّدي المتصفِّح الآخرين مدى أهمية دعمهم.

يمكنك إرسال تغريدة إلى @ChromiumDev باستخدام الهاشتاغ #WebShareTarget وإعلامنا بمكان استخدامك لها وطريقة استخدامك لها.