Skip to content

docs(flows): handle permission requests from flows on every SDK - #893

Draft
acrius wants to merge 5 commits into
mainfrom
docs/flow-permission-requests
Draft

acrius wants to merge 5 commits into
mainfrom
docs/flow-permission-requests

Conversation

@acrius

@acrius acrius commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Flows get a Request permission action that asks users to allow push notifications. The Adapty SDK doesn't show the system dialog: it passes the request to the app, which shows the dialog and returns the answer to the flow. This PR documents both sides.

Important

These articles describe a Flow & Paywall Builder action that isn't released yet. Merge this PR only after the action ships in the builder.

Rollout order: the builder ships the action with a "Your app must handle this request" warning that has no links; then this PR is published; then the builder warning gets links to the seven *-handle-permissions guides.

What changed

New: Handle permission requests in flows, one guide per SDK (*-handle-permissions, added to each platform sidebar after Respond to actions). All seven share one outline: Before you start, How the flow requests a permission, Implement the handler, Register the handler (iOS: pass it to the flow configuration; Android: pass the listener), Test the permission request.

SDK Min version stated App answers in Without a handler Handler throws
iOS 4.0.0 AdaptySystemRequestsHandler, passed to AdaptyUI.getFlowConfiguration(systemRequestsHandler:) No dialog; the flow stays on the screen Can't throw
Android 4.0.0 onShowRequestPermission on the flow event listener AdaptyFlowDefaultEventListener answers false: no dialog, After response runs at once Not caught by the SDK
React Native 4.0.0 onRequestPermission handler on each flow view Answers denied with a log warning: no dialog, After response runs at once (iOS and Android) Answers denied
Flutter 4.0.0 AdaptyUISystemRequestsHandler via AdaptyUI().setSystemRequestsHandler() No answer; the flow stays (iOS and Android) No answer; the flow stays
Unity 4.1.0, and 4.3.0 on Android IAdaptyUISystemRequestsHandler via Adapty.SetSystemRequestsHandler() Console warning, no answer; the flow stays (iOS and Android) Logged, no answer; the flow stays
Kotlin Multiplatform 4.1.0 (4.0 shipped only as betas) AdaptyUISystemRequestsHandler via AdaptyUI.setSystemRequestsHandler() No answer; the flow stays (iOS and Android) The app crashes
Capacitor 4.1.0 (4.0 shipped only as betas) onRequestPermission handler on each flow view Same as React Native Answers denied

Unity needs 4.3.0 on Android because in 4.1.x an answer sent from an OS permission callback reaches the flow only after the flow closes (Unity SDK changelog, 4.3.0-beta.1).

Builder side: Actions (onboarding-actions) gets a Request permission section: the On Tap / On Screen Appear triggers, the After response section, when the request is sent again, advice on which trigger to use, and a warning that lists, per Adapty SDK, what the flow does when the app doesn't answer, and how to keep the flow away from app versions without the handler (an audience on App version (current)). The Action order list and the custom-action use cases now point to it. Respond to purchase outcomes lists Request permission among the actions an outcome can't hold.

Ripple:

  • Every Respond to actions page (*-handle-paywall-actions, iOS handle-paywall-actions) gets the same ## Handle permission requests section, plus a one-line pointer under the intro.
  • The Android, React Native, Capacitor, Flutter and Unity events pages, and the Capacitor, Flutter, KMP and Unity v4 migration guides, no longer say flows don't send permission requests.
  • iOS get-pb-paywalls: the systemRequestsHandler row is rewritten and moved to the end of the table, so that the table follows the Swift argument order of getFlowConfiguration.
  • Context mill: the seven guides are assigned to sdk-flows-display (family handle-permissions), and the sdk-flows-display and flow-logic briefs record the verified per-SDK behavior and the ripple.

Review and verification

  • Multi-role review (editor skill): two mobile developers, two Adapty developers checking claims against the SDK code, two editors, and two product reviewers, merged into one review. Its fixes are in the follow-up commits. The existing articles were treated as the approved outline.
  • Facts were checked in the public SDK repos (iOS 4.0.0–4.4.0, Android to 4.4.0, React Native to 4.3.10 with @adapty/core 4.3.3, Flutter to 4.3.1, Unity to 4.3.0-beta.1, KMP to 4.3.0-beta.1, Capacitor to 4.3.0 with @adapty/core 4.3.4).
  • Code samples:
    • Swift: type-checked under Swift 6 against copies of the SDK declarations.
    • Dart: dart analyze passed. The code has changed only in one comment since.
    • React Native and Capacitor TypeScript: tsc --strict against react-native-adapty 4.3.10 and @adapty/capacitor 4.3.0.
    • Kotlin (Android, KMP) and C# (Unity): not compiled.
  • node scripts/lint-mdx.mjs: all files OK. node scripts/lint-prose.mjs: candidates reviewed, nothing left that the editor rules flag.
  • npm run check-links-diff: 0 broken. 2 stale anchors, both GitHub README anchors the checker can't see (one on an unchanged line).
  • npm run dev: all seven guides, Actions, Respond to purchase outcomes and the Respond to actions pages render, with the expected headings, callouts and the #request-permission anchor.

Before merge

  • The Request permission action ships in the Flow & Paywall Builder.
  • Capture request-permission-action.webp (the Edit action window of Request permission) and replace the placeholder note in onboarding-actions.
  • Android device check for the cross-platform SDKs: on Android, Flutter, Unity, KMP and React Native before 4.3.0 show a modal flow in a separate activity, while permission libraries ask from the app's activity underneath. Android delivers permission results to an activity only when it resumes, so the answer may reach the flow only after it closes. The KMP example already asks from the resumed activity. Check Flutter (createFlowView + present()), Unity and React Native 4.2.x on an Android 13+ device with a clean install. If the flow stays on the screen after the user answers, add a warning to those guides.
  • Compile the Kotlin and C# examples, or run them on a device.

After publishing

  • Link the builder's "Your app must handle this request" warning on the Request permission action to the seven *-handle-permissions guides (a builder change that follows this PR).

🤖 Generated with Claude Code

dbastrikin and others added 5 commits November 20, 2026 12:54
Flows can now ask users to allow push notifications with the Request
permission action. Each SDK gets an article on answering the request
from the app (iOS, Android, Flutter, React Native, Unity, KMP,
Capacitor), linked from Respond to actions and the sidebars.

The notes saying flows don't trigger permission requests are replaced
on the actions, events and v4 migration pages. The iOS getFlowConfiguration
parameter table follows the signature order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add a Request permission section to Actions: the triggers it is offered
on, the After response section, when the request is sent again, and a
warning that names, per Adapty SDK, what the flow does when the app
doesn't answer, with links to the seven SDK guides. The Action order list
and the custom-action use cases now point to it, and purchase outcomes
list it among the actions an outcome can't hold.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The seven SDK guides now share one outline: before you start, how the
flow requests a permission, implement the handler, register it, test.
Each states what happens without a handler and when the handler throws,
as the SDK code does it. Minimum versions are KMP and Capacitor 4.1.0,
Unity 4.1.0 and 4.3.0 on Android. Handlers only ask for the permission,
the Android dialog needs targetSdk 33, the KMP example asks from the
resumed activity, and the metadata titles fit 60 characters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each Respond to actions page gets a Handle permission requests section
that says where the request goes and what happens without a handler,
plus a pointer under the intro. The events pages and v4 migration
guides no longer call the handler reserved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e permission request

Assign the seven handle-permissions guides to sdk-flows-display, record
the per-SDK no-handler and throw behavior with evidence, the open
Android modal-activity question, and the ripple of the builder section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant