Announcing the GrowthRail React Native SDK

Mobile is eating the world, and React Native is increasingly becoming the framework of choice for teams building high-velocity, cross-platform applications.

This guide explains how the @growthrail/react-native SDK fits into a production mobile referral flow. Check the current package and documentation for the supported release rather than copying a version from an older article.

What's included in 1.0?

A React Native integration has to bridge JavaScript, iOS, and Android behavior rather than wrap a REST endpoint alone. Deep-link handling, application identity, and native UI all need explicit platform configuration and tests.

• Drop-in UI Components: We've included a complete, highly-customizable "Invite Friends" screen. You can pass your own theme tokens, or let it automatically match your app's native light/dark mode.
• Deferred Deep Link Handling: Automatic interception and parsing of GrowthRail links. The SDK handles the heavy lifting of extracting referral codes on first boot.
• Explicit network failure handling: Mobile connections are unreliable. The SDK reports request failures so the host app can preserve its own user experience and retry at an appropriate point rather than implying a conversion was recorded.

Performance First

Mobile teams should measure the SDK in their own release build rather than rely on a universal bundle-size claim. The integration is split into core APIs and UI packages so teams can choose the surface they need, and the current setup requirements are documented for each supported platform.

Check out the GitHub repository for example apps, comprehensive documentation, and integration guides. We can't wait to see what you build!

Decide Which Layer Owns Each Responsibility

A React Native referral integration spans JavaScript, two native platforms, your authentication state, and a backend conversion source. Keep those responsibilities explicit. The SDK can capture links, associate the current application user, and present referral UI. Your backend or verified provider integration proves the qualifying conversion. Your reward service applies the credit, entitlement, or payout.

This separation prevents a client screen from becoming financial authority. A user can modify client traffic, repeat an action, or close the app after a network response. The server should evaluate eligibility against durable referral and conversion state, then issue a retry-safe reward event.

Before installing a package, draw the complete sequence for iOS and Android: link opened, app launched or installed, referral context processed, user authenticated, identity initialized, conversion verified, reward delivered, and status displayed. That diagram becomes the test plan.

Install and Configure Native Dependencies Deliberately

Follow the current GrowthRail React Native documentation for package names and supported versions rather than copying an old article snippet. React Native projects vary: a bare app, an Expo development build, and a framework-managed app may require different native configuration and rebuild steps.

Commit the package-manager lockfile and native dependency resolution changes together. On iOS, verify the CocoaPods or Swift package result used by the app target. On Android, verify repository configuration, minimum SDK, Kotlin and Java compatibility, and the dependency graph for each build variant. A JavaScript-only hot reload cannot validate a newly added native module.

Store publishable mobile project credentials in the platform's build configuration, not as private server secrets. Never bundle backend API keys or webhook signing secrets. Use separate project configuration for development, staging, and production so test referrals cannot enter production analytics.

Initialize Once, Then Bind the Authenticated User

Configure the SDK in the application startup path that runs once for the native process. Re-rendering a React provider should not repeatedly create native listeners or replay initialization. Make startup failure non-fatal: record diagnostics and keep the core product usable when referral infrastructure is unavailable.

After authentication resolves, initialize or update the GrowthRail application user with your own stable, non-email identifier. Do not create a new identifier on every launch. When the account signs out, clear user-scoped SDK state before another account signs in on the same device.

Authentication restoration is asynchronous in many apps. Represent three states—unknown, signed out, and signed in—rather than treating the first render as signed out. Binding a temporary anonymous identity and immediately replacing it can split one journey unless that transition is intentionally supported and tested.

Configure iOS Universal Links

Add the required associated domain to the correct iOS application target and host a valid association file over HTTPS. The app identifier, team identifier, path rules, and production domain must agree. Apple's associated domains guide is the primary reference.

Forward URLs received while the app is cold and while it is already running. If a navigation library also consumes links, decide which layer parses the referral parameter and ensure both do not apply conflicting routes. Preserve the intended product destination after referral context is recorded.

Test on a physical device with a clean install. Association files are cached, and simulator behavior does not reproduce every App Store or messaging-app path. Verify that an invalid or unrelated URL opens safely without changing referral state.

Configure Android App Links

Declare HTTPS intent filters for the production referral host and publish the matching Digital Asset Links file. Include the signing certificate fingerprints for the builds users will actually install. The Android App Links documentation provides verification and testing commands.

Forward the initial intent and later intents delivered to an existing activity. Account for launch modes and navigation state so a second link does not recreate the whole application unexpectedly. If Play install-referrer context is used, consume it idempotently and record whether the result was available, unavailable, or already processed.

Test debug, internal, and production signatures separately. A link that verifies for a locally signed build can fail for the Play-distributed artifact when fingerprints or application identifiers differ.

Integrate With React Navigation Without Losing Context

React Native's Linking documentation distinguishes the initial URL from URL events received while the app is open. Your integration needs both. Parse only recognized hosts and parameters, hand referral context to the SDK once, and then route the user to the intended screen.

Do not make referral parsing the only gate before rendering navigation. Apply a bounded startup timeout or process in parallel so an unavailable network cannot hold the user on a splash screen. If attribution finishes later, bind it to the authenticated user according to the documented state machine.

Keep link handling observable in development builds without logging secrets or raw personal data. A concise record of source, recognized route, processing outcome, and correlation identifier is usually enough to debug configuration.

Present Referral UI as Product UI

Choose a modal, drawer, inline surface, or fully custom screen based on the host application's interaction model. Make the entry point reachable from a stable account or settings location, then add contextual prompts only after genuine value moments. Do not interrupt onboarding, payment, permission requests, or failure recovery with a referral ask.

Show the share message and destination before sending. Use the native share sheet where appropriate, preserve accessibility labels and focus order, and provide a copy-link fallback. A status screen should distinguish invited, qualified, pending reward, delivered, rejected, and expired states in language customers can understand.

Remote campaign configuration should have a safe default. If configuration is missing or malformed, hide the optional referral surface rather than crashing a primary screen.

Verify Conversion and Reward Handling on the Server

Mobile receipt or subscription state should be verified by the system that owns it. Connect supported purchase providers or send server-authoritative conversion events; do not grant a reward because the app displayed a success message. Store provider event identifiers so duplicate notifications do not create duplicate conversions.

Verify reward webhook signatures against the raw body, enqueue the business action, and deduplicate on the stable delivery identifier. Respond quickly after durable acceptance. If delivery is retried, return the recorded success for an event already applied.

Exercise failure cases with a staging campaign: duplicate link handling, delayed authentication, duplicate purchase events, webhook timeout after success, manual replay, logout and account switch, and an app launch with no match. The architecture guide explains the backend invariants, while the install-gap guide covers attribution uncertainty in more detail.

Ship With a Release Checklist

1. Confirm production project credentials and application identifiers.
2. Verify iOS association and Android asset-link files from public HTTPS URLs.
3. Test cold-start and warm-start links on release-signed physical devices.
4. Confirm sign-in, sign-out, account switching, and deletion behavior.
5. Run one authoritative conversion through to an idempotent reward delivery.
6. Check that unavailable referral services do not block the core application.
7. Review customer-facing eligibility and incentive disclosure copy.

Re-run this checklist for native dependency upgrades and major operating-system releases. Referral behavior crosses systems that can change independently, so a green JavaScript test suite is necessary but not sufficient evidence of a working production journey.

Add the checklist to the application's normal release process and record the artifact, device, operating-system version, link source, and result. When a native SDK or association file changes, compare that evidence with the previous release. This keeps referral validation reproducible instead of depending on one developer remembering a successful test.

Monitor the first production sessions after release for link-processing errors, identity initialization failures, and reward-delivery lag. Remove sensitive values from diagnostics, set actionable alert thresholds, and retain enough correlation data to reproduce a reported journey safely.