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

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

Pete LePage

Joe Medley

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

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

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

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

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

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

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

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

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

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

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

إذا كان تطبيقك المستهدَف لا يقبل سوى المعلومات الأساسية مثل البيانات أو الروابط وإضافة ما يلي إلى ملف 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);
    })());
  }
});

التحقق من المحتوى الذي تمت مشاركته

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

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

دعم المتصفح

يمكن استخدام Web Share Target API على النحو الموضّح أدناه:

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

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

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

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

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

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