Odbieranie udostępnionych danych za pomocą interfejsu Web Share Target API

Udostępnianie na urządzeniach mobilnych i komputerach uproszczone dzięki interfejsowi Web Share Target API

Pete LePage

Joe Medley

Na urządzeniu mobilnym lub komputerze udostępnianie powinno być tak proste, jak kliknięcie przycisku Udostępnij, wybranie aplikacji i określenie, komu chcesz udostępnić treści. Możesz na przykład udostępnić ciekawy artykuł, wysyłając go e-mailem do znajomych lub tweetując go na cały świat.

Wcześniej tylko aplikacje na konkretne platformy mogły rejestrować się w systemie operacyjnym, aby otrzymywać udostępnienia z innych zainstalowanych aplikacji. Dzięki interfejsowi Web Share Target API zainstalowane aplikacje internetowe mogą zarejestrować się w podstawowym systemie operacyjnym jako docelowe miejsce udostępniania, aby otrzymywać udostępniane treści.

Uwaga: interfejs Web Share Target API to tylko połowa sukcesu. Aplikacje internetowe mogą udostępniać dane, pliki, linki lub tekst za pomocą interfejsu Web Share API. Więcej informacji znajdziesz w interfejsie Web Share API.

Selektor miejsca docelowego udostępniania na poziomie systemu z zainstalowaną aplikacją PWA.

Zobacz działanie celu udziału w internecie

1. Jeśli używasz Chrome w wersji 76 lub nowszej na Androida albo Chrome w wersji 89 lub nowszej na komputerze, otwórz prezentację dotyczącą celu udostępniania w internecie.
2. Gdy pojawi się komunikat, kliknij Zainstaluj, aby dodać aplikację do ekranu głównego, lub użyj menu Chrome, aby dodać ją do ekranu głównego.
3. Otwórz dowolną aplikację obsługującą udostępnianie lub użyj przycisku Udostępnij w aplikacji demonstracyjnej.
4. W selektorze kierowania wybierz Test udostępniania w internecie.

Po udostępnieniu wszystkie udostępnione informacje powinny być widoczne w docelowej aplikacji internetowej.

Rejestrowanie aplikacji jako miejsca docelowego udostępniania

Aby zarejestrować aplikację jako docelowe miejsce udostępniania, musi ona spełniać kryteria instalacji Chrome. Poza tym zanim użytkownik będzie mógł udostępnić coś w aplikacji, musi dodać go do ekranu głównego. Dzięki temu witryny nie będą się przypadkowo dodawać do listy wyboru intencji udostępnienia użytkownika, a użytkownicy będą zadowoleni z udostępniania Twojej aplikacji.

Aktualizowanie pliku manifestu aplikacji internetowej

Aby zarejestrować aplikację jako docel udostępniania, dodaj do jej pliku manifestu aplikacji internetowej wpis share_target. Dzięki temu system operacyjny powinien uwzględnić Twoją aplikację jako opcję w selektorze intencji. To, co dodasz do pliku manifestu, steruje danymi akceptowanymi przez aplikację. Istnieją 3 typowe scenariusze dotyczące wpisu share_target:

• Akceptowanie podstawowych informacji
• Akceptuję zmiany w zgłoszeniu
• Akceptowanie plików

Uwaga: w jednym pliku manifestu może występować tylko 1 element share_target. Jeśli chcesz udostępniać różne miejsca w aplikacji, podaj je jako opcje na stronie docelowej udostępniania (stronie określonej przez element url).

Akceptowanie podstawowych informacji

Jeśli docelowa aplikacja akceptuje tylko podstawowe informacje, takie jak dane, linki i tekst, dodaj do pliku manifest.json:

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

Jeśli Twoja aplikacja ma już schemat adresu URL udostępniania, możesz zastąpić wartości params swoimi dotychczasowymi parametrami zapytania. Jeśli na przykład schemat udostępniania adresu URL używa parametru body zamiast text, możesz zastąpić "text": "text" parametrem "text": "body".

Jeśli nie podasz wartości method, zostanie ona domyślnie ustawiona na "GET". Pole enctype, które nie jest widoczne w tym przykładzie, wskazuje typ kodowania danych. W przypadku metody "GET" parametr enctype ma domyślnie wartość "application/x-www-form-urlencoded" i jest ignorowany, jeśli zostanie ustawiony na inną wartość.

Akceptuję zmiany w zgłoszeniu

Jeśli udostępnione dane w jakiś sposób zmieniają aplikację docelową (np. zapisują w niej zakładkę), ustaw wartość method na "POST" i uwzględnij pole enctype. Przykład poniżej tworzy zakładkę w aplikacji docelowej, więc używa "POST" dla method i "multipart/form-data" dla enctype:

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

Akceptowanie plików

Tak jak w przypadku zmian w aplikacji, akceptacja plików wymaga, by pole method miało wartość "POST" i był dostępny enctype. Dodatkowo enctype musi być "multipart/form-data", a musi zostać dodany wpis files.

Musisz też dodać tablicę files określającą typy plików akceptowanych przez Twoją aplikację. Elementy tablicy to wpisy z 2 składowymi: polem name i polem accept. Pole accept przyjmuje typ MIME, rozszerzenie pliku lub tablicę zawierającą oba te elementy. Najlepiej jest podać tablicę zawierającą zarówno typ MIME, jak i rozszerzenie pliku, ponieważ różne systemy operacyjne preferują.

{
  "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"
        }
      ]
    }
  }
}

Obsługa przychodzących treści

Sposób postępowania z przychodzącymi udostępnionymi danymi zależy od Ciebie i od Twojej aplikacji. Na przykład:

• Klient poczty e-mail może utworzyć nowy e-mail, którego tematem będzie title, a treść będzie zawierać połączone ze sobą ciągi znaków text i url.
• Aplikacja do obsługi sieci społecznościowych może utworzyć nowy post, ignorując title, używając text jako treści wiadomości i dodając url jako link. Jeśli text jest nieobecny, aplikacja może użyć url w treści. Jeśli brakuje elementu url, aplikacja może skanować text w celu znalezienia adresu URL i dodania go jako linku.
• Aplikacja do udostępniania zdjęć może utworzyć nowy pokaz slajdów, używając pola title jako tytułu pokazu, text jako opisu i files jako obrazów w pokazie slajdów.
• Aplikacja do obsługi wiadomości tekstowych może utworzyć nową wiadomość, łącząc text i url, a następnie odrzucając title.

Przetwarzanie udostępnień GET

Jeśli użytkownik wybierze Twoją aplikację, a wartość parametru method to "GET" (wartość domyślna), przeglądarka otworzy nowe okno z adresem URL action. Następnie przeglądarka generuje ciąg zapytania, używając wartości zakodowanych w adresie URL i podanych w pliku manifestu. Jeśli na przykład aplikacja do udostępniania udostępnia funkcje title i text, ciąg zapytania to ?title=hello&text=world. Aby to zrobić, użyj na stronie na pierwszym planie odbiornika zdarzeń DOMContentLoaded i przeanalizuj ciąg zapytania:

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

Używaj skryptu service worker do pobierania z wyprzedzeniem strony action, aby wczytywała się szybko i działała niezawodnie, nawet gdy użytkownik jest offline. Workbox to narzędzie, które ułatwia wdrożenie wstępnego buforowania w skrypcie service worker.

Przetwarzanie udostępnień POST

Jeśli method to "POST", co oznacza, że aplikacja docelowa akceptuje zapisane zakładki lub udostępnione pliki, treść przychodzącego żądania POST zawiera dane przekazane przez aplikację do udostępniania, zakodowane za pomocą wartości enctype podanej w manifeście.

Strona na pierwszym planie nie może przetwarzać tych danych bezpośrednio. Strona widzi dane jako żądanie, więc przekazuje je do skryptu service worker, w którym możesz je przechwycić za pomocą detektora zdarzeń fetch. Tutaj możesz przekazać dane z powrotem do strony głównej za pomocą funkcji postMessage() lub przekazać je na serwer:

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

Weryfikowanie udostępnionych treści

Wybrana aplikacja do udostępniania.

Pamiętaj, aby zweryfikować przychodzące dane. Niestety nie ma gwarancji, że inne aplikacje udostępnią odpowiednie treści w odpowiednim parametrze.

Na przykład na Androidzie pole url będzie puste, ponieważ nie jest obsługiwane w systemie udostępniania Androida. Zamiast tego adresy URL często pojawiają się w polu text lub czasami w polu title.

Obsługa przeglądarek

Interfejs Web Share Target API jest obsługiwany w sposób opisany poniżej:

Na wszystkich platformach aplikacja internetowa musi być zainstalowana, aby mogła się wyświetlać jako potencjalny odbiorca udostępnianych danych.

Przykładowe zastosowania

• Squoosh
• Scrapbook PWA

Pokaż informacje o pomocy dotyczącej interfejsu API

Zamierzasz używać interfejsu Web Share Target API? Twoje publiczne wsparcie pomaga zespołowi Chromium priorytetowo traktować funkcje i pokazuje innym dostawcom przeglądarek, jak ważne jest, aby wspierać te funkcje.

Wyślij tweeta do @ChromiumDev, używając hashtaga #WebShareTarget, i podaj, gdzie i jak go używasz.