Native.App API Reference

Overview

Native.App provides a unified interface for opening native applications across different platforms with cross-platform compatibility.

Interface

App

Main interface for native app operations.

interface App {
  open: (options: AppOpenOptions, target?: WindowProxy) => Promise<AppOpenState>;
  messenger: Messenger;
}

Methods

Native.App.open()

Opens a native application with platform-specific configurations.

Syntax

Native.App.open(options: AppOpenOptions, target?: WindowProxy): Promise<AppOpenState>

Parameters

Platform Options

Each platform requires different configuration parameters:

Android

{
  [Native.Constant.OS.Android]: {
    scheme: string;      // App URL scheme
    packageName: string; // Android package name
  }
}

iOS

{
  [Native.Constant.OS.iOS]: {
    scheme: string;      // App URL scheme
    packageName: string; // Bundle ID
    trackId?: string;    // App Store track ID (optional)
  }
}

Windows

{
  [Native.Constant.OS.Windows]: {
    scheme: string;    // App URL scheme
    productId: string; // Microsoft Store product ID
  }
}

macOS

{
  [Native.Constant.OS.MacOS]: {
    scheme: string;      // App URL scheme
    packageName: string; // Bundle ID
    trackId?: string;    // App Store track ID (optional)
  }
}

Examples

Basic Usage

Open Microsoft Excel across all platforms:

// Create a new tab for the app to open in
const newTab: WindowProxy = window.open("about:blank");

// Configure Excel for all platforms
const excelConfig = {
  [Native.Constant.OS.Android]: {
    scheme: "excel://",
    packageName: "com.microsoft.office.excel",
  },
  [Native.Constant.OS.iOS]: {
    scheme: "excel://",
    packageName: "com.microsoft.Office.Excel",
    // trackId: "586683407", // Uncomment if needed
  },
  [Native.Constant.OS.Windows]: {
    scheme: "excel://",
    productId: "cfq7ttc0k5bf",
  },
  [Native.Constant.OS.MacOS]: {
    scheme: "excel://",
    packageName: "com.microsoft.Excel",
    // trackId: "462058435", // Uncomment if needed
  }
};

// Open Excel
try {
  const result = await Native.App.open(excelConfig, newTab);
  console.log('Excel opened successfully:', result);
} catch (error) {
  console.error('Failed to open Excel:', error);
}

Single Platform Example

Open an app on a specific platform:

// Android only
const androidConfig = {
  [Native.Constant.OS.Android]: {
    scheme: "myapp://",
    packageName: "com.example.myapp",
  }
};

await Native.App.open(androidConfig);

Return Value

Returns Promise<AppOpenState> with information about the app opening state.

Error Handling

The method may reject with errors in the following cases:

• App is not installed on the device
• Invalid configuration parameters
• Platform not supported
• Network connectivity issues

try {
  await Native.App.open(config);
} catch (error) {
  if (error.code === 'APP_NOT_FOUND') {
    // Handle app not installed
  } else if (error.code === 'INVALID_CONFIG') {
    // Handle configuration error
  }
}

Best Practices

✅ Do

• Always provide configurations for all target platforms
• Use window.open("about:blank") for better user experience
• Handle errors gracefully with try-catch blocks
• Test on all target platforms

❌ Don't

• Hardcode platform detection in your application logic
• Ignore error handling
• Use deprecated package names or schemes

Platform-Specific Notes

Android

• Package names follow reverse domain notation
• Ensure the app supports the specified URL scheme

iOS

• Bundle IDs are case-sensitive
• Track IDs are optional but recommended for App Store linking

Windows

• Product IDs can be found in the Microsoft Store URL
• Some apps may require additional permissions

macOS

• Bundle IDs should match the app's Info.plist
• Track IDs link to Mac App Store entries