Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/apis/open-external-purchase-link and https://openiap.dev/llms.txt. Follow the reading instructions, detailed reference, and linked guides relevant to my task before making changes.
Inspect my existing project and reuse its framework and conventions. Ask me for missing product decisions. Implement the requested behavior and run the applicable checks.
Show the working result, the commands and actual test results, and any remaining limitations. Keep your explanation brief.

My request: [describe what customers should be able to do]
See an example request →

openExternalPurchaseLink

Show the store's required disclosure, open the external purchase link only after the user continues, and return the token to report from your server. The disclosure cannot be skipped.

Available in Client Protocol 1.5.0 / openiap-apple 4.2.0 / openiap-google 4.2.0 (requires iOS 17.4+ or Play Billing 8.2.1+).

  • iOS 18.1+: shows the ExternalPurchaseCustomLink notice, then requests a token of apple.tokenType (default acquisition; use link-out in Japan and Brazil) and opens the URL.
  • iOS 17.4 to 18.0: shows the ExternalPurchase notice sheet, which returns the token, then opens the URL. Use a link listed under SKExternalPurchaseLink (or SKExternalPurchaseMultiLink) in Info.plist.
  • Google Play: creates external offer reporting details, then calls launchExternalLink, which shows Play's dialog before opening the link.
  • Amazon, Meta Horizon, Vega OS, macOS, watchOS, iOS before 17.4: returns unavailable without showing anything. An app that still links out on iOS 16 to 17.3 keeps the deprecated presentExternalPurchaseLinkIOS for those versions until client protocol 2.0.0.

Signature

swift
func openExternalPurchaseLink(
    _ request: ExternalPurchaseLinkRequest
) async throws -> ExternalPurchaseLinkResult

Parameters#

  • url (required): the web checkout to open.
  • apple.tokenType: the iOS 18.1+ token type. Ignored on iOS 17.4 to 18.0.

On Google Play the link always opens as a digital content offer (link-to-digital-content-offer). For another link type, such as an app download, skip this call and use the Play program calls directly. Play lists app downloads under the external content links program, and the download link must be approved in Play Console:

ts
// Android only: link to an app download.
// Check isBillingProgramAvailableAndroid('external-content-link') first.
const {externalTransactionToken} =
  await createBillingProgramReportingDetailsAndroid('external-content-link');
// Save or send the token now: the user may not come back to the app.
await api.saveExternalTransactionToken(externalTransactionToken);
await launchExternalLinkAndroid({
  billingProgram: 'external-content-link',
  launchMode: 'launch-in-external-browser-or-app',
  linkType: 'link-to-app-download',
  linkUri: 'https://example.com/app',
});

Returns#

  • status: opened (the user continued and the link opened), cancelled (the user dismissed the disclosure; nothing opened), or unavailable (nothing was shown).
  • reportToken: present only when opened. Play's externalTransactionToken or Apple's external purchase token. OpenIAP never sends it anywhere. Apple requires every token in your monthly report, even when no purchase follows.
  • platform: the platform that produced the token.

Throws#

cancelled and unavailable are results, not errors. A store failure, a missing token, or a link that cannot open throws, for example service-error or not-prepared. Android also needs a current Activity. Godot emits purchase_error and returns null.

Example

swift
let result = try await OpenIapModule.shared.openExternalPurchaseLink(
    ExternalPurchaseLinkRequest(url: "https://example.com/checkout")
)
if result.status == .opened, let token = result.reportToken {
    // Send token to your backend.
}