קבלת נתונים משותפים באמצעות Web Share Target API

שיתוף בנייד ובמחשב פשוט יותר באמצעות Web Share Target API

Pete LePage

Joe Medley

במכשיר נייד או במחשב, השיתוף אמור להיות פשוט כמו לחיצה על הלחצן שיתוף, בחירת אפליקציה ובחירת האנשים שאיתם רוצים לשתף. לדוגמה, יכול להיות שתרצו לשתף מאמר מעניין באימייל עם חברים או לפרסם אותו ב-Twitter לכל העולם.

בעבר, רק אפליקציות ספציפיות לפלטפורמה יכלו להירשם למערכת ההפעלה כדי לקבל שיתופי תוכן מאפליקציות אחרות שמותקנות במכשיר. עם Web Share Target API, אפליקציות אינטרנט מותקנות יכולות להירשם למערכת ההפעלה הבסיסית כיעד שיתוף כדי לקבל תוכן ששותף.

הצגת יעד 'שיתוף באינטרנט' בפעולה

1. פותחים את הדגמה של יעד לשיתוף באינטרנט באמצעות Chrome מגרסה 76 ואילך ל-Android, או Chrome מגרסה 89 ואילך למחשב.
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, שלא מוצג בדוגמה הזו, מציין את סוג הקידוד של הנתונים. ב-method "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. כדי לעבד את הנתונים האלה, משתמשים ב-event listener של 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'));
});

חשוב להשתמש בקובץ שירות (service worker) כדי לאחסן במטמון מראש את הדף action, כדי שהוא יטעים במהירות ויפעל בצורה מהימנה, גם אם המשתמש לא מחובר לאינטרנט. Workbox הוא כלי שיכול לעזור לכם להטמיע אחסון מראש בקובץ השירות.

מתבצע עיבוד של שיתופים ב-POST

אם הערך של method הוא "POST", כפי שהוא יהיה אם אפליקציית היעד מקבלת סימניות שמורות או קבצים משותפים, גוף הבקשה הנכנסת POST מכיל את הנתונים שהועברו על ידי אפליקציית השיתוף, בקידוד באמצעות הערך enctype שסופק במניפסט.

הדף שבחזית לא יכול לעבד את הנתונים האלה ישירות. מכיוון שהדף רואה את הנתונים כבקשה, הוא מעביר אותם לקובץ השירות (service worker), שבו אפשר ליירט אותם באמצעות מאזין לאירועים מסוג 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 API כפי שמתואר בהמשך:

בכל הפלטפורמות, אפליקציית האינטרנט צריכה להיות מותקנת כדי שתופיע כיעד פוטנציאלי לקבלת נתונים משותפים.

אפליקציות לדוגמה

• סקווש
• אפליקציית PWA ל-Scrapbook

תמיכה ב-API

האם אתם מתכננים להשתמש ב-Web Share Target API? התמיכה הציבורית שלכם עוזרת לצוות Chromium לתעדף תכונות, ומראה לספקי דפדפנים אחרים כמה חשובה התמיכה בהן.

אפשר לשלוח ציוץ אל @ChromiumDev באמצעות ההאשטאג #WebShareTarget ולספר לנו איפה ואיך אתם משתמשים בו.