Bezproblemowa migracja źródła PWA: zmiana domen bez utraty użytkowników

Dibyajyoti Pal

Dan Murphy

Marijn Kruisselbrink

Opublikowano: 3 czerwca 2026 r.

Progresywne aplikacje internetowe (PWA) zrewolucjonizowały internet, oferując wrażenia podobne do aplikacji. Jednak jedna z ich największych zalet była też stałym wyzwaniem: tożsamość aplikacji jest ściśle powiązana z origin strony.

Aby zmienić nazwę marki lub przebudować architekturę (np. przenieść witrynę z www.example.com/social na social.example.com), musieliście się zmierzyć z trudnym dylematem. Nie było sposobu na „przeniesienie” zainstalowanej PWA. Użytkownicy musieli ręcznie odinstalować starą aplikację i znaleźć przycisk instalacji nowej.

Zespół PWA z radością przedstawia migrację pochodzenia PWA w Chrome 150. Ta nowa funkcja platformy umożliwia płynne przenoszenie zainstalowanych PWA do nowego pochodzenia w tej samej witrynie przy minimalnym zakłóceniu pracy użytkownika, a jednocześnie zapewnia mu wystarczającą ilość informacji.

Co umożliwia migracja pochodzenia

Możesz modyfikować architekturę witryny bez pogarszania komfortu użytkowników:

• Swoboda architektury technicznej: zmień poddomenę lub ścieżkę aplikacji.
• Naprawianie stanów podzielonej aplikacji: rozwiąż problem, w którym zmiana start_url bez stabilnego identyfikatora powodowała przypadkowe tworzenie duplikatów instalacji aplikacji.

Użytkownicy mogą migrować swoje aplikacje za pomocą prostego okna aktualizacji. Informacje o migracji są im przekazywane w podobny sposób jak w przypadku standardowej aktualizacji aplikacji. Jednym kliknięciem stara aplikacja jest odinstalowywana, a nowa instalowana i uruchamiana.

Jak przeprowadzić migrację PWA

Aby przeprowadzić migrację PWA, wykonaj te czynności. W dalszej części posta znajdziesz więcej szczegółów:

1. Wdrożenie uzgadniania:
   • Dodaj migrate_from do nowej aplikacji.
   • Dodaj pole allow_migration do pliku /.well-known/web-app-origin-association w starym pochodzeniu.
2. Wybierz zachowanie: suggest (lub puste) pozwala uniknąć przerywania pracy użytkownika, co może być przydatne podczas początkowego wdrażania. force blokuje użytkownika i wymaga migracji, jeśli nie może on nadal korzystać ze starych adresów URL.
3. Aktualizuj starą aplikację: jeśli stara witryna przekierowuje do nowej, użyj właściwości install_url w bloku migrate_from, aby przeglądarka mogła nadal znajdować stary manifest w celu potencjalnych aktualizacji.
4. Zaimplementuj id w manifeście docelowym: Chrome wymaga, aby manifest aplikacji docelowej zawierał pole id. Dzięki temu aplikacja nie popełni częstego błędu polegającego na tworzeniu podzielonych aplikacji przez zmianę start_url bez ustawienia id.

Uzgadnianie dwukierunkowe: jak to działa

Aby zapewnić bezpieczeństwo i zapobiec wrogim przejęciom, migracja wymaga bezpiecznego uzgadniania między starym a nowym pochodzeniem. Uzgadnianie to zapewnia, że obie witryny są kontrolowane przez ten sam podmiot.

Krok 1. Nowa aplikacja deklaruje poprzednika (wymagany)

Dodaj pole migrate_from do manifestu aplikacji internetowej nowej aplikacji.

// Manifest at https://fileman.google.com/manifest.json
{
  "name": "File Manager",
  "id": "/files/",
  "start_url": "/files/index.html",
  ....
  "migrate_from": [
    "https://drive.google.com/"
  ]
}

Krok 2. Stare pochodzenie potwierdza migrację (wymagany)

Aby uniemożliwić nowej witrynie jednostronne przejęcie starej aplikacji, stare pochodzenie musi wyraźnie zezwolić na migrację. W tym celu używa pliku konfiguracyjnego .well-known.

// File at https://drive.google.com/.well-known/web-app-origin-association
{
  "https://fileman.google.com/files/": {
    "allow_migration": true
  }
}

Krok 3. Proaktywne sygnalizowanie (opcjonalne)

Aby wywołać aktualizację bez czekania, aż użytkownik odwiedzi nową witrynę, zaktualizuj manifest starej aplikacji, aby wskazywał nową.

// Manifest at https://drive.google.com/manifest.json
{
  "name": "Drive",
  "start_url": "/",
  "migrate_to": {
    "id": "https://fileman.google.com/files/",
    "install_url": "https://fileman.google.com/drive/installwebapp?usp=migrate"
  }
}

Krok 4. Obsługa przekierowań (opcjonalne)

Alternatywnie do użycia pola migrate_to możesz zasygnalizować migrację przekierowując stare adresy URL aplikacji do nowej aplikacji i polegając na scope_extensions aby baner poza zakresem nie wyświetlał się w starej aplikacji. Oznacza to, że manifest starej aplikacji nigdy nie będzie widoczny, a tym samym nie będzie można go zaktualizować. Aby umożliwić dalsze aktualizowanie starej aplikacji przed migracją, ustaw install_url w migrate_from, aby poinformować przeglądarkę o adresie URL, z którego ma pobrać plik, który nadal ma dołączony stary manifest bez przekierowania.

// Manifest at https://fileman.google.com/manifest.json
{
  "name": "File Manager",
  "id": "/files/",
  "start_url": "/files/index.html",
  ....
  "migrate_from": [
    {
      "id": "https://drive.google.com/",
      "install_url": "https://drive.google.com/drive/installwebapp?usp=migrate"
    }
  ]
}

To wszystko. Interfejs użytkownika jest podobny do tego, który jest używany do aktualizowania aplikacji, gdzie użytkownik otrzymuje powiadomienie w prawym górnym rogu okna aplikacji:

Kliknięcie Sprawdź aktualizację aplikacji powoduje wyświetlenie tego interfejsu (w zależności od tego, co zmieniło się w manifeście):

Kontrolowanie komfortu użytkowników

Za pomocą flagi behavior możesz wybrać, jak agresywna ma być migracja:

1. Suggest (domyślnie): użytkownik otrzymuje pasywne powiadomienie (np. w menu aplikacji). Może zaktualizować aplikację, odinstalować ją lub zignorować migrację, uruchamiając okno.
2. Force: przy następnym uruchomieniu aplikacji użytkownik zobaczy blokujące okno. Musi zaktualizować aplikację do nowego pochodzenia lub ją odinstalować (zobacz zrzut ekranu poniżej).

Poniższy przykład pokazuje, jak ustawić ten wybór.

"migrate_from": [
  { 
    "id": "https://example.com/social/",
    "behavior": "force" // or suggest
  }
]

Podsumowanie

Funkcja migracji PWA umożliwia deweloperom dalsze tworzenie nowoczesnych, elastycznych architektur internetowych bez utraty użytkowników.