ExternalPurchaseCustomLink

Introduction

The ExternalPurchaseCustomLink integration enables iOS apps to direct users to external websites for purchasing digital goods and services, in compliance with Apple’s StoreKit External Purchase Link entitlement. This integration handles token retrieval and required user disclosures as mandated by Apple’s guidelines.

Integration name: startiapp.ExternalPurchaseCustomLink

Getting started

This integration is designed for apps that have been approved for the StoreKit External Purchase Link entitlement by Apple. Before using this integration, ensure your app has:

  1. Applied for and received approval for the External Purchase Link entitlement

Methods

show 

show(url: string): Promise<boolean>

Displays the external purchase disclosure notice to the user. If the user accepts, they will be redirected to the specified external purchase URL and true is returned. If the user declines, false is returned and no redirection occurs.

getTokens 

getTokens(): Promise<TokensResponse>

Retrieves the external purchase tokens from StoreKit without showing the disclosure notice to the user. Use this method when you need to obtain tokens programmatically.

Returns: A TokensResponse object containing:

  • isEligible (boolean): Whether the app is eligible for external purchase custom links
  • tokens (optional): Dictionary of tokens by type (e.g., “ACQUISITION”, “SERVICES”)
    • Each token contains: rawToken, decoded, error, and additionalData
  • error (optional): Error code if the request failed
  • message (optional): Human-readable error message
  • raw (optional): Raw response string if deserialization failed

Example:

const response = await startiapp.ExternalPurchaseCustomLink.getTokens();
if (response.isEligible && response.tokens) {
  const acquisitionToken = response.tokens["ACQUISITION"];
  // Send token to your server for verification
}

showNotice 

showNotice(): Promise<NoticeResponse>

Displays Apple’s required external purchase disclosure notice to the user and retrieves tokens upon user consent. This method must be called immediately before redirecting users to an external purchase website.

Important timing: Call this method right before the external redirect, not earlier in your app flow. The tokens received are tied to this specific user interaction and must be used for reporting to Apple.

Returns: A NoticeResponse object containing:

  • isEligible (boolean): Whether the app is eligible for external purchase custom links
  • tokens (optional): Dictionary of tokens by type (same structure as getTokens)
  • status (optional): User’s interaction status: “continued”, “cancelled”, “not_applicable” (when android), or “unknown”
  • error (optional): Error code if the request failed
  • message (optional): Human-readable error message
  • raw (optional): Raw response string if deserialization failed

Example:

const response = await startiapp.ExternalPurchaseCustomLink.showNotice();
if (response.status === "continued" || response.status === "not_applicable") {
  // User accepted, redirect to external purchase immediately
  window.location.href = "https://your-external-purchase-site.com";
} else if (response.status === "cancelled") {
  // User declined, do not proceed with external purchase
}

Events

userTokensReceived 

userTokensReceived(tokens: Record<string, TokenInfo>)

Dispatched when tokens are received from StoreKit. Subscribe to this event at app startup to capture tokens for later reporting to Apple.

Important: Apple requires you to report these tokens as part of your compliance with the External Purchase Link entitlement. Store these tokens securely and send them to your server for inclusion in your reports to Apple.

Event detail: Dictionary of tokens by type, where each token contains:

  • rawToken (optional): The raw Base64URL-encoded token string
  • decoded (optional): Whether the token was successfully decoded
  • error (optional): Error message if token retrieval failed
  • additionalData (optional): Any additional decoded data from the token

Example:

// Subscribe at app initialization
startiapp.ExternalPurchaseCustomLink.addEventListener("userTokensReceived", (event) => {
  const tokens = event.detail;

  // Send to your server
  await fetch("/api/store-apple-tokens", {
    method: "POST",
    body: JSON.stringify(tokens)
  });
});

Token Types

The integration returns two types of tokens:

  • ACQUISITION: Used to verify first-time purchases
  • SERVICES: Used to verify subscription or service-related purchases

Both tokens should be sent to your server for verification according to Apple’s guidelines.

Best Practices

  1. Subscribe to events early: Set up the userTokensReceived event listener at app startup to ensure you capture all tokens for Apple reporting (make sure to store them for your compliance reports)
  2. Call show: Call show(url) with the external purchase URL when the user initiates an external purchase flow
← In-App Purchase
Push notifications →