Skip to main content
The Userpilot Android SDK supports a custom URL scheme that lets you preview experiences on a real device before publishing them, and that carries push notification taps back into your app. Setting it up is two steps: add an <intent-filter> to your AndroidManifest.xml so Android routes matching links to your Activity, then forward the incoming Intent to the Userpilot SDK. The SDK does all the validation, so you hand it every Intent your Activity receives and act on the result.

​
Register the custom URL scheme

Add an intent filter with the custom scheme inside the desired <activity> element. Register it on the Activity that hosts your app, which is usually the one already marked with <action android:name="android.intent.action.MAIN" />. Replace APP_TOKEN with your app’s Userpilot token, which you can obtain from your Environments Page. For example, if your token is NX-12345678, your scheme value is userpilot-nx-12345678. Set android:launchMode="singleTop" so an incoming link is delivered to the running Activity through onNewIntent instead of creating a second instance of it.
Keep android:host="sdk" in this filter. Userpilot validates that the incoming URL uses the sdk host before handling preview or push-notification links.
Use the token exactly as passed to the SDK, in lowercase. Keep the STG- prefix for staging: STG-NX-12345678 uses userpilot-stg-nx-12345678, while NX-12345678 uses userpilot-nx-12345678.

​
Handle the custom URL scheme

Forward the Intent to userpilot.onNewIntent(intent). It returns true if the link was a Userpilot link and the SDK handled it, and false if your app should handle the Intent itself. An Intent reaches your Activity through either onCreate (a cold launch from a link) or onNewIntent (a link that arrives while your app is already running). Override both and forward from each, otherwise links only work in one of the two cases.
onNewIntent takes a single argumentThe signature is onNewIntent(intent: Intent?): Boolean. Earlier guides showed a two-argument form that passed the Activity as well; that overload does not exist. The other overload, onNewIntent(intent: Map<String, Any?>), is for forwarding a push notification payload you already parsed yourself, not for deep links.
The SDK only claims an Intent when the scheme is one of the accepted values, the host is sdk, and the action is VIEW or MAIN. Every other Intent is passed back to your app.
You don’t build the sdk/notification link yourself. The SDK posts each notification with a matching PendingIntent, so a tap arrives at your Activity as a normal deep link and is covered by the same onNewIntent call. See Push Notifications for the delivery setup.

​
Preview an experience with a QR code

Userpilot can render a draft experience on your device before you publish it, so you can check layout, copy, and behavior on a real screen. Preview is supported for Flows and Surveys. The preview is delivered over the custom URL scheme. It works once your app is installed on the device and the scheme is registered and handled as described above.
1

Open the experience

Open a Flow or Survey in the Experience Builder and enter Edit Mode.
2

Start the preview

Select Preview in the top-right corner of the builder. A popup with a QR code appears.
3

Scan the QR code

Scan the code with your device camera. Your app opens and the experience appears.
Points to keep in mind:
  • You don’t need to apply or save your changes before previewing them.
  • The experience doesn’t need to be live.
  • A preview bypasses the experience’s targeting and frequency settings, so it appears even when the current user wouldn’t normally qualify for it.
  • Once you close the experience, the app resumes normal behavior.

​
Test push notifications

You can send a test push to a specific user from the Userpilot dashboard and verify delivery and tap handling on a real device without sending anything to your wider audience. The notification doesn’t need to be live, so you can test it while it’s still a draft.
  • Test pushes work in both the staging and production environments.
  • Test pushes are not counted as real sends, and they’re excluded from analytics.
  • Test pushes bypass the notification’s targeting and frequency settings.
For the dashboard steps, see Mobile push notifications. Because a notification tap arrives as a deep link on Android, a test push also exercises your onNewIntent handling. If the notification appears but tapping it does nothing, the scheme registration is the first thing to check.
Open a link with adb to confirm your scheme is registered and your handler runs, without going through the Builder:
Replace the scheme with your own token and 12345 with a real experience ID. Enable SDK logging during setup to see the SDK report which link it received and what it did with it.

​
Troubleshooting

Confirm the scheme in AndroidManifest.xml matches your token exactly, lowercased. A mismatched scheme means Android never routes the link to your Activity, so your handler is not called at all. Verify the registration with the adb shell am start command above: if adb reports no matching Activity, the intent filter is the problem.
Android routed the link, so registration is correct and the problem is in the handling step. Check that you forward the Intent from both onCreate and onNewIntent. A cold launch only passes through onCreate, so handling just onNewIntent silently drops links that start the app. Also confirm the SDK is set up with the same token that generated the QR code.
Notification taps travel over this same URL scheme, so they need the intent filter and the onNewIntent forwarding described above. Confirm the filter host is exactly sdk.
Each environment has its own token, and the scheme follows the token. Confirm the staging build registers the scheme for the token it initializes the SDK with.