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

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

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

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

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

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

  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 بمَعلمات طلب البحث الحالية. على سبيل المثال، إذا كان body بدلاً من text يُستخدَم في body مخطط مشاركة عنوان URL، يمكنك استبدال "text": "text" بـ "text": "body".

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

جارٍ قبول التغييرات في الطلب

إذا كانت البيانات المشترَكة تغيّر التطبيق المستهدَف بطريقة ما، مثلاً حفظ bookmarked في التطبيق المستهدَف، اضبط قيمة 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" ("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. من هنا، يمكنك إعادة تمرير البيانات إلى foreground الصفحة باستخدام 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 لأنّه غير متاح في نظام المشاركة على Android. بدلاً من ذلك، ستظهر عناوين URL غالبًا في حقل text، أو في حقل title في بعض الأحيان.

دعم المتصفح

تتوفّر واجهة برمجة التطبيقات Web Share Target API على النحو الموضّح أدناه:

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

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

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

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

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