Preserving Installed PWA Users and Push Subscriptions During Domain Migrations

The morning after moving a website to a new domain for a corporate rebrand, support received a wave of identical inquiries: “When I tap the app icon on my home screen, I get an unfamiliar white screen saying ‘This page has moved,’” and “The notification updates I used to receive stopped completely yesterday.” Even though 301 redirects were meticulously configured for every URL, the installed app experience used on the old domain was somehow left behind.

This is no fabrication; it is a pitfall almost inevitably encountered by websites operating Progressive Web Apps (PWAs added to home screens) when changing domains. Search rankings and bookmarks can be preserved via 301 redirects. However, the installed PWA itself, its underlying Service Worker, push notification subscriptions, and client-side stored data reside in an entirely different layer from HTTP redirects. Migrating without accounting for this layer means instantly losing your most engaged users—those who actively used your site as an installed application.

Search ranking preservation and redirects were examined in Domain Migrations and Site Renewal SEO. This article intentionally sets those aside to focus exclusively on client-side state transfers: PWAs, installation status, and push notification subscriptions.

Why standard redirects break web apps

Examining what a PWA actually consists of reveals why domain migrations break functionality. A PWA added to a home screen is not simply a web page on a server; it is a client-side registration recorded by the browser as an installed application tied to a specific origin (https://ドメイン名). Behind the scenes, three core components are bound together on an origin-by-origin basis:

• Service Worker: A background script handling offline functionality, caching, and notification delivery. It can only register against pages belonging to its own origin.
• Push subscriptions: The permission and endpoint granting authorization to send notifications to that specific browser and device, anchored to the Service Worker registration.
• Stored data (IndexedDB, Cache Storage, etc.): Client-side storage containing login states, drafts, and offline caches, isolated per origin.

This is where the web's fundamental security foundation—the same-origin policy—comes into play. A Service Worker under old.example.com cannot control pages under new.example.jp, nor can new.example.jp directly access push subscriptions obtained under old.example.com. The moment the origin changes, the browser views them as completely separate, unrelated entities.

Consequently, here is what transpires during a domain migration. Users visiting the old domain are forwarded to the new domain via a 301 redirect. Because the new domain represents a new origin, the browser treats it as a first-time visit. Meanwhile, the installed PWA on the old domain remains stranded in limbo; tapping the home screen icon attempts to open the old origin, which no longer hosts app content. Servers continue broadcasting notifications to the old origin's subscription endpoints, but because users never open the old domain, those subscriptions expire quietly without renewing. This is how app icons break and push notification reach drops to zero.

旧: https://old-corp.example.com   ← ホーム画面のPWA / SW / 通知購読 / 保存データ
        │ 301リダイレクト（ページは飛ぶ）
        ▼
新: https://newbrand.example.jp     ← 別オリジン。上の4つは何も引き継がれない

The web pages redirect, but the underlying application instance does not. Teams that meticulously configure redirects for every single URL are often the ones who overlook this layer and first discover the failure in production.

What Chrome's Web App Origin Migration can and cannot transfer

To address this problem, Chrome has introduced Web App Origin Migration. Outlined in the Chrome Developers article “Seamless PWA origin migration: Change domains without losing users,” this mechanism allows the identity of an installed PWA to transfer to a new origin by declaring source and target origins within the web app manifests.

The mechanism relies on two manifest fields and an ownership verification handshake. In the new origin's manifest, migrate_from points to the source origin, while in the old origin's manifest, migrate_to points to the target origin.

// 新オリジン newbrand.example.jp の manifest.webmanifest
{
  "name": "NewBrand",
  "id": "/",
  "start_url": "/",
  // 旧オリジンのインストール済みPWAを引き継ぐ宣言
  "migrate_from": [
    { "origin": "https://old-corp.example.com", "behavior": "suggest" }
  ]
}

Additionally, an ownership verification file (.well-known) is placed on the old origin to prove authorization for the transfer. This mutual verification prevents unauthorized third parties from hijacking another organization's PWA (such as malicious actors declaring migrations for phishing purposes).

// 旧オリジン側 https://old-corp.example.com/.well-known/web-app-origin-association
{
  "https://newbrand.example.jp/": { "allow_migration": true }
}

In terms of user experience, when users are directed from the old site to the new site, the browser detects this declaration and displays a confirmation dialog similar to a standard app update. With a single tap, the old PWA is uninstalled, and the new PWA is installed and launched. Specifying force in behavior forces the update, whereas suggest leaves it as a suggestion (there is also a constraint that name and icon changes cannot occur simultaneously with the migration, reflecting instead as a standard app update after migration finishes).

Here, two premises are absolutely essential when making decisions for ordering custom development.

First, this mechanism is limited to same-site origin migrations. It can therefore handle migrations that change subdomains or paths, such as from app.example.com to example.com/app/. However, a move from old-corp.com to newbrand.jp is an example of a migration that changes the registered domain itself—the common case of moving to a completely different domain after a company name change—and is outside its scope. The specification deliberately excludes migrations between different sites because of risks such as phishing. When a rebranding project involves moving to a completely different domain, the design must start from the assumption that this Chrome feature cannot handle it.

Second: The migration only preserves the PWA's "installation identity"; it does not carry over the content. Various permissions, starting with notification approvals, along with stored data accumulated in IndexedDB or Cache Storage, fall outside the migration scope, and the new origin is in principle treated as a "clean, new installation." Keeping notification subscriptions alive and transferring stored data is not the browser's responsibility, but ours (the server and implementation).

Furthermore, this feature is still in the process of standardization as a specification (under discussion in W3C/WICG), and browser support is currently led by Chromium-based browsers. Equivalent behavior cannot be expected on other environments such as Safari/iOS at this time. It should be clearly noted that when adopting this for production, you must verify the target user base's browser composition and the latest support status.

Designing to Keep Notification Subscriptions and Stored Data Alive "In-House"

Since Chrome's feature is restricted to the same site, rebranding projects moving to a different domain must rely on an architecture where we handle data transfer ourselves rather than leaving it to the browser. The key implementation points for custom development come down to the following three.

First is retaining notification subscriptions on the server side. Push notifications can only be sent if the server possesses the "per-device subscription information (endpoint and keys)." Rather than leaving this to the old origin's client side, saving it in the server database linked to user accounts ensures the server-side destination remains even after the domain changes. However, as noted earlier, subscriptions themselves are bound to an origin, making a flow to reacquire subscriptions (prompting resubscription) on the new origin indispensable post-migration. For logged-in users, this flow requests notification permission again on the new origin and overwrites the old account record with the new subscription.

Next is implementing the pushsubscriptionchange event. Service workers have an event called pushsubscriptionchange that fires when a subscription is renewed or expires due to browser requirements. Adding logic here to fetch a new subscription and resend it to the server improves resilience against everyday subscription expirations, not just during migrations.

// service-worker.js（新オリジン側）
self.addEventListener('pushsubscriptionchange', (event) => {
  event.waitUntil(
    self.registration.pushManager
      .subscribe(event.oldSubscription.options) // 同じ条件で取り直し
      .then((newSubscription) =>
        // 新しい購読をサーバーへ。古い購読と差し替える
        fetch('/api/push/resubscribe', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            old: event.oldSubscription,
            new: newSubscription,
          }),
        })
      )
  );
});

Finally, the transfer policy for stored data. Origin-isolated storage such as IndexedDB cannot be moved automatically. For data where "loss leads to user churn," such as login state and user preferences, the robust approach is to sync it to the server prior to migration and reconstruct it from the server upon the first login on the new origin. Conversely, make the call to discard recalculable caches rather than forcing a transfer. This is a design decision that draws the line between what to carry over and what to discard, starting from "what loss would upset users," which is a matter of priorities rather than technology.

What Happened in Our Client Project

In a rebranding project for a certain retailer (company name withheld) that was sending shipping status push notifications to members, we almost stepped right into this pitfall. The initial migration plan was designed around search equity: "redirect all URLs with 301s and monitor rankings in Search Console and GA4." While reasonable as a redirect strategy, the PWA and notification layer had slipped entirely out of scope.

During staging verification, we checked "how many members have added the site to their home screen on the old domain" and "how many notification subscriptions are active." It turned out that a substantial portion of active subscriptions belonged to repeat users who utilized it like an app—specifically, the high-LTV regular customer segment. Proceeding with the naive migration would have preserved search traffic while wiping out notifications overnight for the very regulars who drove revenue the most.

Because it was a migration to a different domain, Chrome's origin migration feature could not be used, so we pivoted to an in-house resubscription flow. Specifically, we implemented a three-tier approach: (1) save subscription information linked to member accounts on the server before migration, (2) re-request notification permissions upon the initial login on the new domain, and (3) treat old subscriptions as expired and replace them on the server side. In addition, rather than immediately decommissioning the old domain after migration, we maintained an interim period displaying a re-installation path for members visiting the old domain, asking them to "please reinstall the app on the new domain." As a result, post-migration notification reach recovered steadily, keeping regular customer churn to a minimum.

What we learned from this project is that transferring PWAs and notifications is not just "one task within the migration process"; it belongs to the stage where you inventory 'who uses which features and to what extent' before formulating the migration plan. You cannot enter migration design without knowing the count of installed users and their business significance. For reviewing the baseline before introducing or managing a PWA, reading our PWA Implementation Guide for Small and Medium Businesses will help clarify your company's current standing.

Points to Confirm Before Ordering

As the party ordering a renewal involving a domain migration, checking several aspects of your company's status before receiving quotes or proposals will streamline discussions. Have you run initiatives prompting home screen additions (PWA installation)? Are you sending push notifications, how many subscriptions exist, and what customer segments use them? Is the new domain same-site with the old domain (differing only by subdomain), or is it a completely separate domain? These three factors drastically alter the implementation workload required for the migration.

When receiving proposals, if a migration plan only discusses redirects and SEO, try asking: "How will PWA installation states and notification subscriptions be transferred?" Whether you receive a concrete answer serves as a touchstone to evaluate the fidelity of their migration architecture. When determining the timing for initiating a renewal itself, our article on website renewal timing should also serve as a useful reference.

At GleamHub, we provide end-to-end support for designing PWA and notification subscription transitions during domain migrations and site consolidations, from current-state inventorying to post-launch resubscription funnels. If you want to move to a different domain for a rebrand but avoid losing the regulars who added your app and their notifications, feel free to reach out via our contact form. After reviewing your current subscription status and browser demographics, we will collaborate with you right from defining what to carry over and what to discard.

Sources

• Seamless PWA origin migration: Change domains without losing users（Chrome for Developers）
• PWA Origin Migration Explainer（WICG/manifest-incubations）
• Ready for Developer Testing: Web App Origin Migration（blink-dev）
• ServiceWorkerGlobalScope: pushsubscriptionchange event（MDN）
• Progressive Web Apps in multi-origin sites（web.dev）