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

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

Pete LePage

Joe Medley

Aby udostępnić coś na urządzeniu mobilnym lub komputerze, wystarczy kliknąć przycisk Udostępnij, wybrać aplikację i wskazać, komu chcesz ją udostępnić. Możesz na przykład udostępnić ciekawy artykuł, wysyłając go e-mailem do znajomych lub tweetując na całym świecie.

Wcześniej tylko aplikacje na konkretnej platformie mogły rejestrować się w systemie operacyjnym, aby otrzymywać dane o udostępnieniach z innych zainstalowanych aplikacji. Jednak za pomocą interfejsu Web Share Target API zainstalowane aplikacje internetowe mogą zarejestrować się w bazowym systemie operacyjnym jako cel udostępniania treści udostępnianych.

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

Selektor celu udostępniania na poziomie systemu z zainstalowaną aplikacją PWA jako opcją.

Zobacz działanie celu udostępniania w internecie

1. W Chrome w wersji 76 lub nowszej na Androida albo Chrome w wersji 89 lub nowszej na komputerze otwórz prezentację celu udostępniania w sieci.
2. Gdy pojawi się prośba, kliknij Zainstaluj, by dodać aplikację do ekranu głównego, lub dodaj ją do ekranu głównego, korzystając z menu Chrome.
3. Otwórz dowolną aplikację, która obsługuje udostępnianie, lub użyj w niej przycisku Udostępnij.
4. W selektorze celu kliknij Test udostępniania w internecie.

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

Rejestrowanie aplikacji jako miejsca docelowego udziału

Aby zarejestrować aplikację jako cel udostępniania, musi ona spełniać kryteria instalacji w Chrome. Poza tym, zanim użytkownik będzie mógł udostępnić coś w Twojej aplikacji, musi ją dodać do ekranu głównego. Zapobiega to przypadkowemu dodawaniu stron do okna wyboru intencji udostępniania i sprawia, że użytkownicy chcą wykonywać działania związane z aplikacją.

Aktualizowanie pliku manifestu aplikacji internetowej

Aby zarejestrować aplikację jako cel udostępniania, dodaj wpis share_target do pliku manifestu aplikacji internetowej. Dzięki temu system operacyjny ma dodać Twoją aplikację jako opcję w selektorze intencji. To, co dodasz do pliku manifestu, określa, jakie dane akceptuje aplikacja. Istnieją 3 typowe scenariusze w przypadku wpisu share_target:

• Akceptowanie informacji podstawowych
• Akceptowanie zmian w aplikacji
• Akceptuję pliki

Uwaga: w każdym pliku manifestu możesz mieć tylko 1 element share_target. Jeśli chcesz udostępnić plik w różnych miejscach w aplikacji, podaj tę opcję na docelowej stronie docelowej udostępniania (stronie określonej we wpisie url).

Akceptowanie informacji podstawowych

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

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

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

Jeśli nie podano żadnej wartości, method przyjmuje domyślnie wartość "GET". Pole enctype, które nie zostało pokazane w tym przykładzie, wskazuje typ kodowania danych. W przypadku metody "GET" właściwość enctype przyjmuje domyślnie wartość "application/x-www-form-urlencoded" i jest ignorowana, jeśli ma inną wartość.

Akceptowanie zmian w aplikacji

Jeśli udostępnione dane zmienią w jakiś sposób aplikację docelową – np. zapisanie zakładki w aplikacji docelowej – ustaw wartość method na "POST" i uwzględnij pole enctype. Poniższy przykład 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"
    }
  }
}

Akceptuję pliki

Tak jak w przypadku zmian w aplikacji, akceptacja plików wymaga, aby method zawierał "POST" i element enctype. Dodatkowo enctype musi mieć wartość "multipart/form-data" i należy dodać wpis files.

Musisz też dodać tablicę files definiującą typy plików, które akceptuje Twoja aplikacja. Elementy tablicy to wpisy z 2 elementami: polem name i polem accept. Pole accept może zawierać typ MIME, rozszerzenie pliku lub tablicę zawierającą oba te elementy. Najlepiej udostępnić tablicę zawierającą zarówno typ MIME, jak i rozszerzenie pliku, ponieważ preferowane są systemy operacyjne.

{
  "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 treści przychodzących

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

• Klient poczty e-mail może utworzyć wersję roboczą nowego e-maila, używając jako tematu e-maila title, którego treść to text i url.
• Aplikacja społecznościowa może utworzyć wersję roboczą nowego posta z pominięciem atrybutu title, użyć text jako treści i dodać url jako link. Jeśli brakuje text, aplikacja może też użyć elementu url w treści. Jeśli brakuje parametru url, aplikacja może przeskanować plik text w poszukiwaniu adresu URL i dodać go jako link.
• Aplikacja do udostępniania zdjęć może utworzyć nowy pokaz slajdów, używając elementu title jako tytułu pokazu slajdów, text jako opisu i files jako obrazu pokazu slajdów.
• Aplikacja do obsługi SMS-ów może utworzyć wersję roboczą nowej wiadomości przy użyciu połączonych operatorów text i url, a potem pomijania tych elementów: title.

Przetwarzam udziały GET

Jeśli użytkownik wybierze Twoją aplikację, a method ma wartość "GET" (domyślnie), przeglądarka otworzy nowe okno pod adresem URL action. Przeglądarka wygeneruje ciąg zapytania, korzystając z zakodowanych w adresie URL wartości podanych w pliku manifestu. Jeśli na przykład aplikacja do udostępniania udostępnia parametry title i text, ciąg zapytania to ?title=hello&text=world. Aby to przetworzyć, użyj na pierwszym planie detektora 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'));
});

Pamiętaj, by użyć skryptu service worker, by wczytać stronę action w pamięci podręcznej. Dzięki temu będzie się szybko ładować i działać niezawodnie nawet wtedy, gdy użytkownik jest offline. Pole robocze to narzędzie, które pomoże Ci wdrożyć wstępne buforowanie w skrypcie service worker.

Przetwarzanie udziałów POST

Jeśli method to "POST", tak jakby aplikacja docelowa akceptuje zapisane zakładki lub udostępnione pliki, treść przychodzącego żądania POST zawiera dane przekazywane przez aplikację do udostępniania zakodowane z użyciem wartości enctype podanej w pliku manifestu.

Strona na pierwszym planie nie może bezpośrednio przetwarzać tych danych. Strona traktuje dane jako żądanie, więc przekazuje je do skryptu service worker, z którego możesz przechwycić dane za pomocą detektora zdarzeń fetch. Następnie możesz przekazać dane z powrotem na stronę na pierwszym planie za pomocą tagu 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);
    })());
  }
});

Weryfikuję udostępnione treści

Przykładowa aplikacja docelowa do udostępniania.

Pamiętaj, aby zweryfikować przychodzące dane. Nie ma jednak gwarancji, że inne aplikacje udostępnią odpowiednią treść we właściwym parametrze.

Na przykład na Androidzie pole url będzie puste, ponieważ nie obsługuje go system udostępniania Androida. Zamiast tego adresy URL będą często wyświetlane w polu text lub czasami w polu title.

Obsługiwane przeglądarki

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

Na wszystkich platformach aplikacja internetowa musi być zainstalowana, zanim pojawi się jako potencjalny cel otrzymywania udostępnianych danych.

Przykładowe aplikacje

• Squoosh
• PWA notatnika

Pokaż obsługę interfejsu API

Czy zamierzasz używać interfejsu Web Share Target API? Twoja publiczna pomoc pomaga zespołowi Chromium priorytetowo traktować funkcje i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wsparcie.

Wyślij tweeta na adres @ChromiumDev, używając hashtagu #WebShareTarget, i daj nam znać, gdzie i w jaki sposób go używasz.