# Related Applications

## Overview

The `related_applications` property allows you to specify native applications available on different platforms (App Store, Play Store, Microsoft Store, etc.). Combined with `prefer_related_applications`, browsers can suggest installing the native app instead of or alongside the PWA.

**Use Cases**:

* You have both a PWA and native mobile apps
* You want to promote the native app for better platform integration
* You want users to discover all versions of your app
* You need platform-specific features only available in native apps

## Configuration

### Basic Related Applications

List related native apps without preferring them:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        prefer_related_applications: false  # Don't prefer native apps
        related_applications:
            - platform: "play"
              url: "https://play.google.com/store/apps/details?id=com.example.app"
              id: "com.example.app"
```

{% endcode %}

**Result**: Browser shows PWA install prompt. Native apps listed as alternatives.

### Prefer Native Applications

Suggest native apps over PWA installation:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        prefer_related_applications: true  # Prefer native apps
        related_applications:
            - platform: "play"
              url: "https://play.google.com/store/apps/details?id=com.example.app"
              id: "com.example.app"
            - platform: "itunes"
              url: "https://apps.apple.com/app/example-app/id123456789"
```

{% endcode %}

**Result**: Browser suggests installing native app first, PWA as fallback.

### Multiple Platforms

List apps for all major platforms:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        prefer_related_applications: false
        related_applications:
            - platform: "play"
              url: "https://play.google.com/store/apps/details?id=com.example.app"
              id: "com.example.app"
            - platform: "itunes"
              url: "https://apps.apple.com/app/example-app/id123456789"
              id: "123456789"
            - platform: "windows"
              url: "https://apps.microsoft.com/store/detail/example-app/9NBLGGH4NNS1"
              id: "9NBLGGH4NNS1"
            - platform: "chrome_web_store"
              url: "https://chrome.google.com/webstore/detail/example-app/abcdefghijklmnopqrstu"
              id: "abcdefghijklmnopqrstu"
```

{% endcode %}

## Properties

### prefer\_related\_applications

**Type**: `boolean` **Default**: `false`

Controls whether browsers should suggest native apps over the PWA.

| Value   | Behavior                                    |
| ------- | ------------------------------------------- |
| `false` | PWA is primary, native apps as alternatives |
| `true`  | Native apps preferred, PWA as fallback      |

**When to use `true`**:

* Native app provides significantly better experience
* Platform-specific features are critical
* Native app is your primary product
* PWA is mainly for web compatibility

**When to use `false`** (default):

* PWA is your primary product
* Want maximum reach across all platforms
* Native app is optional enhancement
* PWA feature parity with native apps

### platform

**Type**: `string` (required)

Identifier for the app platform.

## Supported Platforms

### play (Google Play Store)

**For**: Android devices

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "play"
      url: "https://play.google.com/store/apps/details?id=com.example.myapp"
      id: "com.example.myapp"
```

{% endcode %}

**URL Format**: `https://play.google.com/store/apps/details?id={package_name}`

**ID Format**: Java package name (e.g., `com.company.app`)

**Finding your package name**:

1. Open Play Console
2. Go to your app
3. Check "Package name" field
4. Or find in `build.gradle`: `applicationId "com.example.app"`

### itunes (Apple App Store)

**For**: iOS, iPadOS devices

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "itunes"
      url: "https://apps.apple.com/app/example-app/id123456789"
      id: "123456789"
```

{% endcode %}

**URL Format**: `https://apps.apple.com/app/{app-name}/id{app_id}`

**ID Format**: Numeric App ID (e.g., `123456789`)

**Finding your App ID**:

1. Open App Store Connect
2. Go to your app
3. Check "Apple ID" field
4. Or find in App Store URL after `/id`

### windows (Microsoft Store)

**For**: Windows 10/11 devices

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "windows"
      url: "https://apps.microsoft.com/store/detail/9NBLGGH4NNS1"
      id: "9NBLGGH4NNS1"
```

{% endcode %}

**URL Format**: `https://apps.microsoft.com/store/detail/{store_id}`

**ID Format**: Store ID starting with 9 (e.g., `9NBLGGH4NNS1`)

**Finding your Store ID**:

1. Open Partner Center
2. Go to your app
3. Check "Store ID" field
4. Or find in Microsoft Store URL

### chrome\_web\_store (Chrome Web Store)

**For**: Chrome Extensions/Apps

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "chrome_web_store"
      url: "https://chrome.google.com/webstore/detail/abcdefghijklmnopqrst"
      id: "abcdefghijklmnopqrst"
```

{% endcode %}

**URL Format**: `https://chrome.google.com/webstore/detail/{extension_id}`

**ID Format**: 32-character extension ID

**Finding your Extension ID**:

1. Open Chrome Web Store Developer Dashboard
2. Go to your extension
3. Check "Item ID" field
4. Or find in extension URL

### chromeos\_play (Chrome OS Play Store)

**For**: Chrome OS devices with Play Store support

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "chromeos_play"
      url: "https://play.google.com/store/apps/details?id=com.example.app"
      id: "com.example.app"
```

{% endcode %}

**Format**: Same as Google Play Store

### webapp (Web Apps)

**For**: Generic web applications

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "webapp"
      url: "https://app.example.com/install"
```

{% endcode %}

**URL Format**: Any URL to your web app

### f-droid (F-Droid)

**For**: Android open-source app repository

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "f-droid"
      url: "https://f-droid.org/packages/com.example.app"
      id: "com.example.app"
```

{% endcode %}

**URL Format**: `https://f-droid.org/packages/{package_name}`

### amazon (Amazon Appstore)

**For**: Amazon Fire devices, Android

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
related_applications:
    - platform: "amazon"
      url: "https://www.amazon.com/dp/B0123456789"
      id: "B0123456789"
```

{% endcode %}

**URL Format**: `https://www.amazon.com/dp/{asin}`

**ID Format**: ASIN (Amazon Standard Identification Number)

## Complete Examples

### Example 1: Social Media App

PWA primary, native apps as enhancements:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        name: "SocialApp"
        description: "Connect with friends"
        prefer_related_applications: false  # PWA is primary
        related_applications:
            # Android native app
            - platform: "play"
              url: "https://play.google.com/store/apps/details?id=com.socialapp"
              id: "com.socialapp"

            # iOS native app
            - platform: "itunes"
              url: "https://apps.apple.com/app/socialapp/id987654321"
              id: "987654321"
```

{% endcode %}

### Example 2: Game

Native apps preferred for performance:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        name: "Epic Game"
        description: "Play the best game ever"
        prefer_related_applications: true  # Prefer native for performance
        related_applications:
            - platform: "play"
              url: "https://play.google.com/store/apps/details?id=com.epic.game"
              id: "com.epic.game"

            - platform: "itunes"
              url: "https://apps.apple.com/app/epic-game/id111222333"
              id: "111222333"

            - platform: "windows"
              url: "https://apps.microsoft.com/store/detail/9NBLGGH4GAME"
              id: "9NBLGGH4GAME"
```

{% endcode %}

### Example 3: Productivity Tool

Available on all platforms:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        name: "TaskMaster Pro"
        prefer_related_applications: false
        related_applications:
            - platform: "play"
              url: "https://play.google.com/store/apps/details?id=com.taskmaster.pro"
              id: "com.taskmaster.pro"

            - platform: "itunes"
              url: "https://apps.apple.com/app/taskmaster-pro/id555666777"
              id: "555666777"

            - platform: "windows"
              url: "https://apps.microsoft.com/store/detail/9TASKMASTER123"
              id: "9TASKMASTER123"

            - platform: "chrome_web_store"
              url: "https://chrome.google.com/webstore/detail/taskmaster/abcdefghijkl"
              id: "abcdefghijkl"

            - platform: "f-droid"
              url: "https://f-droid.org/packages/com.taskmaster.pro"
              id: "com.taskmaster.pro"
```

{% endcode %}

### Example 4: PWA-Only with Web App Link

No native apps, just PWA:

{% code title="/config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    manifest:
        name: "Web-Only App"
        prefer_related_applications: false
        related_applications:
            - platform: "webapp"
              url: "https://webapp.example.com"
```

{% endcode %}

## Browser Support

| Browser          | Support | Behavior                                  |
| ---------------- | ------- | ----------------------------------------- |
| Chrome (Android) | ✅       | May show native app banner if prefer=true |
| Chrome (Desktop) | ⚠️      | Limited support                           |
| Edge             | ⚠️      | Limited support                           |
| Safari           | ❌       | Ignored                                   |
| Firefox          | ❌       | Ignored                                   |

{% hint style="info" %}
**Graceful Degradation**: Browsers that don't support this feature simply ignore it and show standard PWA install prompts.
{% endhint %}

## User Experience Flow

### When prefer\_related\_applications = false

```
User visits PWA
    ↓
Browser shows: "Add to Home Screen" (PWA)
    ↓
User installs PWA
    ↓
[Optional] "Also available on Google Play" link shown
```

### When prefer\_related\_applications = true

```
User visits PWA (on Android)
    ↓
Browser checks: Native app available on Play Store?
    ↓
Yes: Shows "Get the app" banner → Play Store
    ↓
No: Falls back to "Add to Home Screen" (PWA)
```

## Testing

### 1. Check Manifest

{% code title="JavaScript Console" lineNumbers="true" %}

```javascript
fetch('/manifest.json')
    .then(r => r.json())
    .then(manifest => {
        console.log('Prefer native:', manifest.prefer_related_applications);
        console.log('Related apps:', manifest.related_applications);

        manifest.related_applications?.forEach(app => {
            console.log(`Platform: ${app.platform}`);
            console.log(`URL: ${app.url}`);
            console.log(`ID: ${app.id}`);
        });
    });
```

{% endcode %}

### 2. Test on Android Chrome

```bash
1. Visit your PWA on Android Chrome
2. If prefer_related_applications = true:
   - Look for native app install banner
   - Banner should link to Play Store
3. If prefer_related_applications = false:
   - Look for PWA install prompt
   - Native app may be mentioned as alternative
```

### 3. Verify Store Links

```bash
# Test each URL
- ✓ Play Store URL opens correct app
- ✓ App Store URL opens correct app
- ✓ Microsoft Store URL opens correct app
- ✓ Chrome Web Store URL opens correct extension
- ✓ All IDs match actual apps
```

### 4. DevTools Inspection

```bash
1. Open DevTools (F12)
2. Go to Application → Manifest
3. Check "Related Applications" section
4. Verify:
   - prefer_related_applications value
   - All platforms listed
   - URLs are correct
   - IDs match
```

## Best Practices

### 1. Keep URLs Updated

```yaml
# ✓ Good - URLs point to active apps
related_applications:
    - platform: "play"
      url: "https://play.google.com/store/apps/details?id=com.active.app"

# ✗ Bad - URL points to removed app
related_applications:
    - platform: "play"
      url: "https://play.google.com/store/apps/details?id=com.old.removed.app"
```

### 2. Include App IDs

```yaml
# ✓ Good - includes ID for better matching
- platform: "play"
  url: "https://play.google.com/store/apps/details?id=com.example.app"
  id: "com.example.app"

# ⚠️ Acceptable but less ideal
- platform: "play"
  url: "https://play.google.com/store/apps/details?id=com.example.app"
```

### 3. List Active Platforms Only

```yaml
# ✓ Good - only lists platforms where app exists
related_applications:
    - platform: "play"
      url: "..."

# ✗ Bad - lists platforms without apps
related_applications:
    - platform: "play"
      url: "..."
    - platform: "itunes"
      url: "..."  # But iOS app doesn't exist!
```

### 4. Use prefer\_related\_applications Sparingly

```yaml
# Default (recommended for most PWAs)
prefer_related_applications: false

# Only use true if native app is significantly better
prefer_related_applications: true
```

### 5. Provide Fallback

Always ensure your PWA works standalone, even when preferring native apps.

## Decision Tree

**Should you prefer native applications?**

```
Does your native app provide significantly better UX?
├─ Yes → Does it have features PWA can't offer?
│         ├─ Yes → prefer_related_applications: true
│         └─ No → prefer_related_applications: false
└─ No → prefer_related_applications: false

Do you want maximum reach?
└─ Yes → prefer_related_applications: false (PWA primary)

Is installation friction a concern?
└─ Yes → prefer_related_applications: false (PWA easier to install)
```

## Common Mistakes

### 1. Wrong ID Format

**Problem**:

```yaml
- platform: "play"
  id: "https://play.google.com/..."  # Wrong! ID is not a URL
```

**Solution**:

```yaml
- platform: "play"
  id: "com.example.app"  # Correct: package name
```

### 2. Missing Platform

**Problem**:

```yaml
related_applications:
    - url: "https://play.google.com/..."  # Missing platform!
```

**Solution**:

```yaml
related_applications:
    - platform: "play"  # Required!
      url: "https://play.google.com/..."
```

### 3. Prefer Without Related Apps

**Problem**:

```yaml
prefer_related_applications: true
# But no related_applications listed!
```

**Solution**:

```yaml
prefer_related_applications: true
related_applications:
    - platform: "play"
      url: "..."  # Must provide apps to prefer
```

### 4. Outdated URLs

**Problem**: URLs point to removed or renamed apps

**Solution**: Regularly verify all store URLs still work

## Troubleshooting

### Native App Banner Not Showing

**Problem**: Expected native app banner doesn't appear

**Checklist**:

* ✓ `prefer_related_applications: true` is set
* ✓ Testing on supported browser (Chrome Android)
* ✓ App actually exists on specified platform
* ✓ URL and ID are correct
* ✓ App is published (not draft)
* ✓ PWA manifest is valid

### Wrong App Suggested

**Problem**: Browser suggests wrong native app

**Solutions**:

* Verify `id` matches the actual app
* Check `platform` is correct
* Ensure URL points to correct store listing
* Clear browser cache and try again

### PWA Install Blocked

**Problem**: Users can't install PWA when prefer=true

**Solutions**:

* Set `prefer_related_applications: false`
* Or ensure native app is available
* Provide manual "Install PWA" link in your app

## Related Documentation

* [PWA Manifest](/1.4.x/the-manifest/complete-example.md) - Complete manifest configuration
* [Installation](/1.4.x/how-to-install-remove-a-pwa.md) - PWA installation guide

## Resources

* **MDN related\_applications**: <https://developer.mozilla.org/en-US/docs/Web/Manifest/related\\_applications>
* **Web.dev**: <https://web.dev/add-manifest/#related\\_applications>
* **W3C Spec**: <https://w3c.github.io/manifest/#related\\_applications-member>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pwa.spomky-labs.com/1.4.x/experimental-features/non-standard-parameters/related-applications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.