# iOS App Store

Canonical HTML: https://p-hatan.com/deeplink-x/stores/ios-app-store/

DeeplinkX 1.5.8.

## Platforms and setup

Native platforms: **ios**.



## Public actions

### IOSAppStore.open


```dart
factory IOSAppStore.open()
```

Launch with `DeeplinkX.launchApp`. Native platforms: **ios**. Action web fallback: **available**. Store-fallback flag: **not supported**.

This constructor takes no parameters.

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/app_stores/ios_app_store.dart#L14)

### IOSAppStore.openAppPage


```dart
static IOSAppStoreOpenAppPageAction openAppPage({ required final String appId, required final String appName, final String mediaType = '8', final String? country, final String? campaignToken, final String? providerToken, final String? affiliateToken, final String? uniqueOrigin, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios**. Action web fallback: **available**. Store-fallback flag: **not supported**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `appId` | `String` | Yes | — |
| `appName` | `String` | Yes | — |
| `mediaType` | `String` | No | `'8'` |
| `country` | `String?` | No | — |
| `campaignToken` | `String?` | No | — |
| `providerToken` | `String?` | No | — |
| `affiliateToken` | `String?` | No | — |
| `uniqueOrigin` | `String?` | No | — |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/app_stores/ios_app_store.dart#L54)

### IOSAppStore.rateApp


```dart
static IOSAppStoreRateAppAction rateApp({ required final String appId, required final String appName, final String mediaType = '8', final String? country, final String? campaignToken, final String? providerToken, final String? affiliateToken, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios**. Action web fallback: **not available**. Store-fallback flag: **not supported**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `appId` | `String` | Yes | — |
| `appName` | `String` | Yes | — |
| `mediaType` | `String` | No | `'8'` |
| `country` | `String?` | No | — |
| `campaignToken` | `String?` | No | — |
| `providerToken` | `String?` | No | — |
| `affiliateToken` | `String?` | No | — |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/app_stores/ios_app_store.dart#L88)


## Provider setup and examples
DeeplinkX provides support for opening the iOS App Store and specific app pages, including app details, reviews, and iMessage extensions.

## Available Actions

### Launch iOS App Store
```dart
final deeplinkX = DeeplinkX();

// Simple launch
await deeplinkX.launchApp(IOSAppStore.open());

// Launch with fallback disabled
await deeplinkX.launchApp(IOSAppStore.open(), disableFallback: true);
```

### Launch App Page Action
```dart
final deeplinkX = DeeplinkX();

// Simple action
await deeplinkX.launchAction(IOSAppStore.openAppPage(
  appId: '284882215',  // Facebook app ID
  appName: 'facebook',
  country: 'us',       // Optional: two-letter country code
));

// Action with fallback disabled
await deeplinkX.launchAction(
  IOSAppStore.openAppPage(
    appId: '284882215',
    appName: 'facebook',
  ),
  disableFallback: true,
);
```

### Launch App Review Page Action
```dart
final deeplinkX = DeeplinkX();

// Simple action
await deeplinkX.launchAction(IOSAppStore.rateApp(
  appId: '284882215',  // Facebook app ID
  appName: 'facebook',
  country: 'us',       // Optional: two-letter country code
));

// Action with fallback disabled
await deeplinkX.launchAction(
  IOSAppStore.rateApp(
    appId: '284882215',
    appName: 'facebook',
  ),
  disableFallback: true,
);
```

## Parameter Validations

### App ID Validation
iOS App Store app IDs must follow these rules:
- Must contain only digits
- Length: 1-10 digits
- Cannot be empty

Example valid app IDs:
- `284882215` (Facebook)
- `310633997` (WhatsApp)
- `389801252` (Instagram)

Example invalid app IDs:
- `abc123` (contains letters)
- `12345678901` (too long)
- `123-456` (contains special characters)

### App Name Validation
App names must follow these rules:
- Must be a valid URL slug format
- Typically lowercase with hyphens instead of spaces
- Should match the app's name in the App Store URL

Example valid app names:
- `facebook`
- `whatsapp-messenger`
- `instagram`

### Optional Parameters
- **country**: Two-letter country code (e.g., 'us', 'uk', 'jp')
- **mediaType**: Specifies content type (default: '8' for iOS apps)
- **campaignToken**: Used for tracking marketing campaigns
- **providerToken**: Numeric identifier for your team/developer
- **affiliateToken**: Used for Apple's affiliate tracking
- **uniqueOrigin**: Indicates the origin of the link

## Platform-Specific Configuration

### iOS
Add the following to your `ios/Runner/Info.plist`:
```xml
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>itms-apps</string>
</array>
```

## URL Schemes

DeeplinkX uses the following URL schemes for iOS App Store:

### Native App Deep Links
When on iOS, the following scheme is used:
- `itms-apps://` - Primary iOS App Store URL scheme
- For app pages: `itms-apps://itunes.apple.com/app/id{appId}`
- For reviews: `itms-apps://itunes.apple.com/app/id{appId}?action=write-review`

### Web Fallback URLs
When on other platforms or when native schemes fail:
- `https://apps.apple.com` - Official App Store web URL
- For app pages: `https://apps.apple.com/{country}/app/{appName}/id{appId}`
- For reviews: `https://apps.apple.com/{country}/app/{appName}/id{appId}?action=write-review`

## Official Documentation
- [Apple Developer Documentation - Universal Links](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content)
- [Apple Developer Documentation - URL Schemes](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content#3001215)
- [Apple Developer Documentation - App Store Connect](https://appstoreconnect.apple.com/help)

## Fallback Behavior
DeeplinkX follows this sequence when handling iOS App Store deeplinks:

1. First, it attempts to launch the iOS App Store app if it's installed on the device.
2. If the iOS App Store app is not installed or the device is not running iOS, DeeplinkX will automatically fall back to opening the iOS App Store web interface in the default browser.
3. You can disable fallbacks by setting `disableFallback: true` in the launch methods.

## Fallback Support for Actions

| Action      | Web Fallback |
| ----------- | ------------ |
| open        | ✅            |
| openAppPage | ✅            |
| rateApp     | ❌            |

Note: Store apps are not considered "fallbackable" in the traditional sense since they are the fallback targets for other apps. However, they do have web fallback behaviors when the store app itself cannot be launched.

## Check If iOS App Store Is Installed

```dart
final deeplinkX = DeeplinkX();
final isInstalled = await deeplinkX.isAppInstalled(IOSAppStore());
```