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]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
ExternalPurchaseCustomLinknotice, then requests a token ofapple.tokenType(defaultacquisition; uselink-outin Japan and Brazil) and opens the URL. - iOS 17.4 to 18.0: shows the
ExternalPurchasenotice sheet, which returns the token, then opens the URL. Use a link listed underSKExternalPurchaseLink(orSKExternalPurchaseMultiLink) 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
unavailablewithout showing anything. An app that still links out on iOS 16 to 17.3 keeps the deprecatedpresentExternalPurchaseLinkIOSfor those versions until client protocol 2.0.0.
Signature
func openExternalPurchaseLink(
_ request: ExternalPurchaseLinkRequest
) async throws -> ExternalPurchaseLinkResultParameters#
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:
// 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), orunavailable(nothing was shown).reportToken: present only whenopened. Play'sexternalTransactionTokenor 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
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.
}See: External Purchase