WebView integration

The WebView integration renders the Footprint onboarding flow inside a native sheet that you control: a page sheet on iOS, a bottom sheet on Android, with your own back button, close button, and toolbar styling. onboarding.initialize, by contrast, launches the flow in an in-app browser.

If your onboarding flow includes identity document verification, declare camera permissions in your app's app.json (or app.config.js). The WebView runs inside your app, so your app's manifest and Info.plist gate the camera prompt, not a system browser.

json
1{
2  "expo": {
3    "ios": {
4      "infoPlist": {
5        "NSCameraUsageDescription": "We use the camera to verify your identity documents."
6      }
7    },
8    "android": {
9      "permissions": ["android.permission.CAMERA"]
10    }
11  }
12}

1. Wrap your app in FootprintWebViewProvider. The provider mounts the native sheet that hosts the Footprint WebView. It must be an ancestor of every component that calls useFootprintWebView().

javascript
1import { FootprintWebViewProvider } from "@onefootprint/footprint-expo";
2
3export default function App() {
4  return (
5    <FootprintWebViewProvider>
6      {/* The rest of your app */}
7    </FootprintWebViewProvider>
8  );
9}

2. Create an onboarding session. Call POST /onboardings and keep the onboarding session token it returns, such as obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH.
3. Launch the flow with the useFootprintWebView hook. When the user taps a button, for example, call initialize with the onboardingSessionToken and an onComplete callback.

javascript
1import { useFootprintWebView } from "@onefootprint/footprint-expo";
2import { View, Button } from "react-native";
3
4const Screen = () => {
5  const { initialize } = useFootprintWebView();
6
7  const launch = () => {
8    initialize({
9      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
10      onComplete: (validationToken) => {
11        console.log(validationToken);
12      },
13    });
14  };
15
16  return (
17    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
18      <Button onPress={launch} title="Launch Footprint" />
19    </View>
20  );
21};

When the user completes the flow, onComplete receives a validationToken. Post it to your backend for further processing.

The SDK also reports errors, cancellation, and closing. Pass onError, onCancel, and onClose to initialize:

typescript
1initialize({
2  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
3  onComplete: (validationToken) => {
4    console.log(validationToken);
5  },
6  onError: (error) => {
7    console.log(error);
8  },
9  onCancel: () => {
10    console.log("User canceled the flow");
11  },
12  onClose: () => {
13    console.log("User closed the flow");
14  },
15});

onCancel fires when the user taps the close button in the toolbar, swipes the sheet down, or taps the backdrop (Android).

Pass an appearance object to initialize to change the look of the flow:

typescript
1initialize({
2  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
3  onComplete: (validationToken) => {
4    console.log(validationToken);
5  },
6  appearance: {
7    variables: {
8      borderRadius: "8px",
9      colorSuccess: "#10b981",
10      colorError: "#F87171",
11      buttonPrimaryBg: "#5550e9",
12    },
13  },
14});

The customization guide lists every variable.

Beyond the in-flow appearance, you can style the native sheet and the toolbar that wraps it. The toolbar shows the Footprint domain, a close button, and, when relevant, a back button.

typescript
1initialize({
2  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
3  onComplete: (validationToken) => {
4    console.log(validationToken);
5  },
6  sheetStyle: {
7    backgroundColor: "#ffffff",
8  },
9  toolbarStyle: {
10    backgroundColor: "#ffffff",
11    buttonColor: "#000000",
12    textColor: "#000000",
13    separatorColor: "#c8c8cc",
14  },
15  options: {
16    hideFootprintUrl: false,
17  },
18});

• Handle the decision validates the token on your backend and reads the onboarding status.
• Changelog lists notable releases of @onefootprint/footprint-expo.