Callbacks
Every callback the SDK calls, its arguments, what its return value means and in which order things happen.
Callbacks are options of presentPaywall, mountPaywall, startAutoPlacements and the React components. The web component has properties and events instead (see Web component).
| Callback | Arguments | Return value |
|---|---|---|
onPurchase | { packageId: string; product?: ProductInfo; answers: Answers } | true or nothing: purchased. false: cancelled. Throw: failed. May be async. |
onRestore | none | true or nothing: restored. false: nothing to restore. May be async. |
onAction | { actionId: string; answers: Answers } | false keeps a presented screen open. Anything else closes it. May be async. |
onAnswer | { fieldId: string; value: string, string[] or undefined; answers: Answers } | none |
onClose | none | none |
onSkip | { reason: 'frequency_cap' or 'audience' or 'holdout' } | none |
onOpenUrl | url: string | none |
onError | error: unknown | none |
onResult | { placement: string; result: PurchaseResult } (auto placements only) | none |
onPurchase
Run your checkout here. While it runs the screen shows a spinner and ignores taps.
- Return
trueor nothing: the SDK records a purchase and, forpresentPaywall, closes with{ outcome: 'purchased', packageId }. - Return
false(the visitor cancelled): a cancel is recorded and the screen stays open. - Throw: a purchase error is recorded, the screen stays open and
onErrorreceives the error. - If you pass no
onPurchase, a purchase tap callsonErrorwithUIKit: pass onPurchase to handle purchase buttons.
product is your own ProductInfo for that package, if you passed products.
onRestore
The Restore purchases button only appears when you pass onRestore. Return false to say nothing was restored. Otherwise a restore is recorded and presentPaywall resolves restored.
onAction
Called when a "Run your code" button is pressed. actionId is the ID set in the editor. It runs while the screen is busy. Screen changes ("Go to another screen", "Back to previous screen") do not call it. With presentPaywall and no onAction, the screen closes and resolves { outcome: 'action', actionId }. mountPaywall never closes the screen.
onAnswer
Called each time a question changes. value is the option ID, a list of option IDs for multiple choice, the typed text, or undefined once cleared. See Answers.
onClose
Called whenever a presented screen ends with closed: a close button, Esc, a backdrop click, a toast timing out, or another presentPaywall replacing it. In mountPaywall it is called when the close button is pressed.
onSkip
Called when a placement's targeting chose to show nothing. See Targeting attributes.
onOpenUrl
Called with the link a visitor pressed. The default opens it in a new tab with noopener,noreferrer. Only http, https, mailto, tel and links that start with a single / reach it. Others call onError.
onError
Receives errors from the renderer, from your own callbacks that throw, and from links that were refused. Load failures of presentPaywall and mountPaywall reject their promise instead. In startAutoPlacements and the React Paywall, load failures go to onError.
Order for a purchase
- The visitor taps buy:
purchase_clickis recorded. onPurchaseruns.- A purchase (or cancel, or error) is recorded.
presentPaywallresolves, ormountPaywallstays.