expo-apple-external-link 1.0.0

package/.eslintrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+  root: true,
+  extends: ['universe/native'],
+  ignorePatterns: ['build'],
+};

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vox Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# Expo Apple External Link
+
+This is a custom [Expo Module](https://docs.expo.dev/modules/overview/) + [Config Plugin](https://docs.expo.dev/config-plugins/introduction/) which enables an iOS app built with Expo to direct users to an external website for account management and creation.
+
+This custom native module is iOS-only.
+
+> [!IMPORTANT]
+> The External Link API requires iOS 16+. You may also need to add `expo-build-properties`.
+
+## External Links
+
+Typically, Apple does not allow apps which contain links to your website on the App Store. Instead, you must implement in-app purchases.
+
+However there is a special exception for "reader" apps. These kinds of apps can optionally apply for an additional Entitlement, and if this is granted then the app will then be allowed on the App Store.
+
+- see https://developer.apple.com/support/reader-apps
+- see https://developer.apple.com/documentation/storekit/external_link_account
+
+## Module
+
+This Expo Module exposes a single method called `openInAppModal()`. This calls [ExternalLinkAccount.open()](https://developer.apple.com/documentation/storekit/externallinkaccount/4047547-open) in native (Swift) code.
+
+## Plugin
+
+The Plugin is responsible for modifying your `Entitlements` and `Info.plist` files, using options passed to the plugin in your `app.json` config.
+
+## Usage
+
+Can be included alongside any other Expo Config Plugins in `app.json`:
+
+```json
+"plugins": [
+    // ...other plugins...
+    [
+        "expo-build-properties",
+        {
+            "ios": {
+                "deploymentTarget": "16.0",
+            },
+        },
+    ],
+    [
+        "expo-apple-external-link",
+        {
+            "externalLinks": {
+                "*": "https://mywebsite.com/subscribe"
+            }
+        }
+    ]
+]
+```
+
+The `externalLinks` Object corresponds to the [SKExternalLinkAccount](https://developer.apple.com/documentation/bundleresources/information_property_list/skexternallinkaccount/) dictionary, and maps country codes to region-specific URLs.
+
+> [!TIP]
+> Alternately, the key `"*"` can be used as a wildcard for all regions.

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require("./plugin/build");

package/build/ExpoAppleExternalLinkModule.d.ts

@@ -0,0 +1,7 @@
+import { NativeModule } from 'expo';
+declare class ExpoAppleExternalLinkModule extends NativeModule {
+    openInAppModal(): Promise<void>;
+}
+declare const _default: ExpoAppleExternalLinkModule;
+export default _default;
+//# sourceMappingURL=ExpoAppleExternalLinkModule.d.ts.map

package/build/ExpoAppleExternalLinkModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpoAppleExternalLinkModule.d.ts","sourceRoot":"","sources":["../src/ExpoAppleExternalLinkModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AAEzD,OAAO,OAAO,2BAA4B,SAAQ,YAAY;IAC5D,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CAChC;;AAGD,wBAAyF"}

package/build/ExpoAppleExternalLinkModule.js

@@ -0,0 +1,4 @@
+import { requireNativeModule } from 'expo';
+// This call loads the native module object from the JSI.
+export default requireNativeModule('ExpoAppleExternalLink');
+//# sourceMappingURL=ExpoAppleExternalLinkModule.js.map

package/build/ExpoAppleExternalLinkModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpoAppleExternalLinkModule.js","sourceRoot":"","sources":["../src/ExpoAppleExternalLinkModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAMzD,yDAAyD;AACzD,eAAe,mBAAmB,CAA8B,uBAAuB,CAAC,CAAC","sourcesContent":["import { NativeModule, requireNativeModule } from 'expo';\n\ndeclare class ExpoAppleExternalLinkModule extends NativeModule {\n  openInAppModal(): Promise<void>;\n}\n\n// This call loads the native module object from the JSI.\nexport default requireNativeModule<ExpoAppleExternalLinkModule>('ExpoAppleExternalLink');\n"]}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './ExpoAppleExternalLinkModule';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC"}

package/build/index.js

@@ -0,0 +1,2 @@
+export { default } from './ExpoAppleExternalLinkModule';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC","sourcesContent":["export { default } from './ExpoAppleExternalLinkModule';\n"]}

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["apple"],
+  "apple": {
+    "modules": ["ExpoAppleExternalLinkModule"]
+  }
+}

package/ios/ExpoAppleExternalLink.podspec

@@ -0,0 +1,29 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'ExpoAppleExternalLink'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = {
+    :ios => '15.1',
+    :tvos => '15.1'
+  }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/voxmedia/expo-apple-external-link' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  # Swift/Objective-C compatibility
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+end

package/ios/ExpoAppleExternalLinkModule.swift

@@ -0,0 +1,44 @@
+import ExpoModulesCore
+import StoreKit
+
+internal class NetworkError: Exception {
+    override var reason: String {
+        "StoreKitError: A network error occurred when communicating with the App Store."
+    }
+}
+
+internal class NotEntitled: Exception {
+    override var reason: String {
+        "StoreKitError: The application is not entitled to perform the action."
+    }
+}
+
+public class ExpoAppleExternalLinkModule: Module {
+    // Each module class must implement the definition function. The definition consists of components
+    // that describes the module's functionality and behavior.
+    // See https://docs.expo.dev/modules/module-api for more details about available components.
+    public func definition() -> ModuleDefinition {
+        // Sets the name of the module that JavaScript code will use to refer to the module. Takes a string as an argument.
+        // Can be inferred from module's class name, but it's recommended to set it explicitly for clarity.
+        // The module will be accessible from `requireNativeModule('ExpoAppleExternalLink')` in JavaScript.
+        Name("ExpoAppleExternalLink")
+        
+        // Defines a JavaScript function that always returns a Promise and whose native code
+        // is by default dispatched on the different thread than the JavaScript runtime runs on
+        AsyncFunction("openInAppModal") { (promise: Promise) in
+            if #available(iOS 16.0, *) {
+                Task {
+                    do {
+                        try await ExternalLinkAccount.open()
+                    } catch StoreKitError.networkError {
+                        promise.reject(NetworkError())
+                    } catch StoreKitError.notEntitled {
+                        promise.reject(NotEntitled())
+                    } catch {
+                        promise.reject(error)
+                    }
+                }
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "expo-apple-external-link",
+  "version": "1.0.0",
+  "description": "Expo module which allows reader apps to link to an external website for account creation or management",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-apple-external-link",
+    "ExpoAppleExternalLink"
+  ],
+  "repository": "https://github.com/voxmedia/expo-apple-external-link",
+  "bugs": {
+    "url": "https://github.com/voxmedia/expo-apple-external-link/issues"
+  },
+  "author": "jpdriver <jpdriver@users.noreply.github.com> (https://github.com/jpdriver)",
+  "license": "MIT",
+  "homepage": "https://github.com/voxmedia/expo-apple-external-link#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "~19.1.1",
+    "expo-module-scripts": "^55.0.2",
+    "expo": "^55.0.8",
+    "react-native": "0.82.1"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  }
+}

package/plugin/build/index.d.ts

@@ -0,0 +1,8 @@
+import { ConfigPlugin } from "expo/config-plugins";
+type ExternalLinks = {
+    [key: string]: string;
+};
+declare const withExternalLinks: ConfigPlugin<{
+    externalLinks: ExternalLinks;
+}>;
+export default withExternalLinks;

package/plugin/build/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("expo/config-plugins");
+const withExternalLinks = (config, { externalLinks }) => {
+    config = (0, config_plugins_1.withEntitlementsPlist)(config, props => {
+        props.modResults["com.apple.developer.storekit.external-link.account"] =
+            true;
+        return props;
+    });
+    config = (0, config_plugins_1.withInfoPlist)(config, props => {
+        props.modResults.SKExternalLinkAccount = externalLinks;
+        return props;
+    });
+    return config;
+};
+exports.default = withExternalLinks;

package/plugin/src/index.ts

@@ -0,0 +1,27 @@
+import {
+  withEntitlementsPlist,
+  withInfoPlist,
+  ConfigPlugin,
+} from "expo/config-plugins";
+
+type ExternalLinks = { [key: string]: string };
+
+const withExternalLinks: ConfigPlugin<{ externalLinks: ExternalLinks }> = (
+  config,
+  { externalLinks },
+) => {
+  config = withEntitlementsPlist(config, props => {
+    props.modResults["com.apple.developer.storekit.external-link.account"] =
+      true;
+    return props;
+  });
+
+  config = withInfoPlist(config, props => {
+    props.modResults.SKExternalLinkAccount = externalLinks;
+    return props;
+  });
+
+  return config;
+};
+
+export default withExternalLinks;

package/plugin/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "expo-module-scripts/tsconfig.plugin",
+    "compilerOptions": {
+      "outDir": "build",
+      "rootDir": "src"
+    },
+    "include": ["./src"],
+    "exclude": ["**/__mocks__/*", "**/__tests__/*"]
+  }
+  

package/plugin/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts"],"version":"5.9.3"}

package/src/ExpoAppleExternalLinkModule.ts

@@ -0,0 +1,8 @@
+import { NativeModule, requireNativeModule } from 'expo';
+
+declare class ExpoAppleExternalLinkModule extends NativeModule {
+  openInAppModal(): Promise<void>;
+}
+
+// This call loads the native module object from the JSI.
+export default requireNativeModule<ExpoAppleExternalLinkModule>('ExpoAppleExternalLink');

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from './ExpoAppleExternalLinkModule';

package/tsconfig.json

@@ -0,0 +1,9 @@
+// @generated by expo-module-scripts
+{
+  "extends": "expo-module-scripts/tsconfig.base",
+  "compilerOptions": {
+    "outDir": "./build"
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*"]
+}