Skip to content
Stack guide · React Native

Clickwrap agreement in React Native

A React Native app shows its acceptance screen in a WebView that loads a page from your own domain, passes the client token in, and gets the record ID back over the message bridge before your server creates the account.

Free plan: 10 live signatures a month and a full test mode. No card required.

8 files · copy and run

The working code: a WebView acceptance screen and its backend

The browser SDK observes real page elements, and a native view has no DOM for it to observe. So the acceptance screen is a small web page on your own domain, shown in react-native-webview. The screen, the page and a four-route Express server are below.

server/routes/ceremony.ts
// server/routes/ceremony.ts
import { randomUUID } from "node:crypto";
import { Router } from "express";
import { db, esc } from "../clients";

export const ceremony = Router();

// POST /api/signup/ceremony creates the session and returns only the client token.
ceremony.post("/api/signup/ceremony", async (req, res) => {
  const { email, country, state } = req.body as { email: string; country: string; state?: string };
  const signerId = randomUUID(); // your identifier for this person. Keep using it for them in later sessions.
  const region = country.toUpperCase() === "US" && state ? `US-${state.toUpperCase()}` : undefined;

  const { data: session, error } = await esc.sessions.create(
    {
      profile: process.env.ESIGNCOMPLY_PROFILE_ID!,
      signer: { external_id: signerId, email, class: "consumer", country: country.toUpperCase(), region },
      documents: [
        { document: process.env.ESIGNCOMPLY_TERMS_ID!, version: "current" },
        { document: process.env.ESIGNCOMPLY_PRIVACY_ID!, version: "current" },
      ],
      // The page the WebView loads. In live mode it must be inside your registered domain.
      context: { url: `${process.env.APP_ORIGIN}/mobile/accept`, locale: "en-US", purpose: "account_signup" },
    },
    { idempotencyKey: `signup-${signerId}` },
  );
  if (error) return res.status(502).json({ error: error.code });

  // Server-owned state: the signer and the versions this session pinned.
  await db.query("insert into acceptances (signer_id, session_id, document_version_ids) values ($1, $2, $3)", [
    signerId,
    session.id,
    session.documents.map((d) => d.version_id),
  ]);

  // Only these go to the app. Never the key, never the whole session.
  res.json({
    ceremonyId: session.id,
    clientToken: session.client_token,
    apiUrl: session.api_url,
    documents: session.documents,
  });
});

What each file does

Eight files on two sides. The app shows a WebView and relays two messages. Your server creates the session, serves the page and the documents, confirms the record and keeps the receipt.

01

ceremony.ts: your API creates the session

server/routes/ceremony.tsView the file

The app never holds the secret key. It posts the email, country and state to this route, and the server calls esc.sessions.create with the Node SDK. context.url is the page the WebView loads: in live mode it has to be inside your registered domain, which is why that page lives on your site and not in the app bundle.

The route saves one acceptances row with the signer ID and the version IDs the session pinned, then returns four things: a ceremony ID (the session ID), the client token, the API URL and the pinned documents.

02

accept.html: the page inside the WebView

server/public/accept.htmlView the file

This is where the acceptance happens. The page holds the notice, the two document links, an unchecked checkbox and the one button, and it loads the browser SDK with a script tag. On load it posts { type: "ready" } to the app through window.ReactNativeWebView.postMessage. The app answers by calling window.startCeremony with the client token, which stays in memory in the page.

From there it is the same ceremony as on the web: EsignComply.attach, presentDocument for each link, observeAssent on the container, and complete() from the signer's real tap. The page then posts { type: "completed", recordId } back to the app. Because the SDK reports straight from the WebView to Esign Comply, the record is an observation of the signer's device, not a statement by your server.

03

AcceptTermsScreen.tsx: the WebView and the bridge

app/screens/AcceptTermsScreen.tsxView the file

The screen renders one WebView pointed at your acceptance page. When the page says it is ready, the screen asks your API for a session and passes the client token in with injectJavaScript. When the page says the ceremony is completed, the screen sends the record ID to your API. If the session expires, the page asks for a new one the same way.

onShouldStartLoadWithRequest keeps the acceptance page loaded: a tap on Terms of Service or Privacy Notice opens the document in the system browser instead of navigating the WebView away. react-native-webview is the community WebView package. There is no Esign Comply package for React Native, and none is needed.

04

finish.ts: confirm the record, then create the account

server/routes/finish.tsView the file

The record ID crossed two boundaries to get here, the WebView and the app, so the server treats it as a claim. It loads the open row for the ceremony ID, reads the record with the secret key (GET /v1/records/{id}) and checks four things: the status is recorded, timestamped or anchored, livemode matches the deployment, the signer ID is the one this server made, and the set of document versions is exactly the set the session pinned.

Only then does it create the user and store the user ID, the record ID, the signed receipt and the accepted time. A second request with the same record finds no open row and gets 409.

05

The migration: one acceptances table

server/migrations/001_acceptances.sqlView the file

One row per ceremony, in Postgres. The first three columns are written when the session is created and are the server-owned state the confirmation compares against. The rest are filled in when the record is confirmed. record_id is unique, so one record opens one account.

06

legal.ts: the registered version, unmodified

server/routes/legal.tsView the file

/legal/terms and /legal/privacy serve the version Esign Comply holds, fetched by the version ID in ?v=, inside <article data-esc-document>. They are on the same origin as the acceptance page on purpose: the browser SDK reads the page behind each link, hashes the article's text and reports it, and the API compares the hash with the registered version (rule CR-08).

07

webhook.ts: the backstop when the app is closed

server/routes/webhook.tsView the file

A phone loses signal, or the app is swiped away right after the tap. record.completed still arrives at your server once the record is sealed. The route keeps the body as raw bytes with express.raw, verifies the signature with verifyWebhookSignature from the Node SDK, and fills in the open row for that session. A repeated delivery finds the row already filled and changes nothing.

08

index.ts and clients.ts: mount the routes, hold the key

server/index.ts and server/clients.tsView the file

The webhook router is mounted before express.json() so that its body is still raw when the signature is checked. clients.ts creates the Node SDK client and the Postgres pool once. The SDK reads the region from the key and retries a 429 by itself.

Test mode

Run it

From an empty account to a sealed test record from a simulator. The server runs on localhost:3000, which test keys accept without a domain.

  1. 01

    Create a free account and a test key

    Sign up, then choose Create test key in the dashboard. The key starts with esc_test_ and is shown once. The Free plan needs no card, and test keys work on localhost on any port with no domain.

  2. 02

    Register your two documents and a signup profile

    In the dashboard, add a document named Terms of Service and one named Privacy Notice, publish a version of each, and create a profile with method checkbox and level L1. The names matter: the notice in the form names each document by its title, and rule CR-02 looks for both. Copy the three IDs.

  3. 03

    Set the server's environment variables

    The key lives on the server only. APP_ORIGIN is where the acceptance page is served.

    .env
    ESIGNCOMPLY_API_KEY=esc_test_us_...       # the test key, shown once in the dashboard
    ESIGNCOMPLY_PROFILE_ID=prof_signup_4f1a   # the signup profile: checkbox, L1
    ESIGNCOMPLY_TERMS_ID=doc_8Hq2             # Terms of Service
    ESIGNCOMPLY_PRIVACY_ID=doc_Pv71           # Privacy Notice
    ESIGNCOMPLY_WEBHOOK_SECRET=whsec_...      # only for the webhook
    APP_ORIGIN="http://localhost:3000"
    DATABASE_URL="postgres://localhost/myapp"
  4. 04

    Install, migrate and start the server

    esigncomply is the Node SDK, and react-native-webview goes into the app. Apply server/migrations/001_acceptances.sql to your database, then start the server.

    $npm install esigncomply express pg && npx tsx --env-file=.env server/index.ts
  5. 05

    Point the app at the server

    Set SITE in the screen to http://localhost:3000. The iOS simulator reaches it as is. For the Android emulator run adb reverse tcp:3000 tcp:3000 so that localhost inside the emulator is your machine. A plain http://192.168.x.x address does not work: the SDK needs HTTPS or localhost to hash the documents, and test keys accept localhost out of the box. For a physical device, serve the page from an HTTPS host and list that host under Domains, Test origins in the dashboard.

  6. 06

    Accept once

    Open the screen in the simulator. The checkbox unlocks when the session is attached. Tick it and tap Create account. The app receives the record ID and your server answers the finish request with 200.

  7. 07

    Open the test record

    The dashboard lists one new test record under Records. It shows what Esign Comply observed from the browser (the page attached, both documents presented, the notice captured, the tick, the signing act), the conformance findings and the evidence report, watermarked TEST. Your acceptances row holds the same record ID and its signed receipt.

  8. 08

    Run the conformance check

    The acceptance page starts when the app hands it a token, so check the session the app just finished. This script asks for a conformance run over that one session and prints the summary and every finding with its rule, the measurement and the fix. The session ID is the session_id of the newest acceptances row. A clean run reports block: 0. The same findings are on the test record in the dashboard.

    scripts/conformance.ts
    // scripts/conformance.ts
    import { EsignComply } from "esigncomply";
    
    // Runs the conformance rules over one finished session and prints the findings.
    async function main() {
      const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY);
      const { data: run, error } = await esc.conformance.run({ session_ids: [process.argv[2]] });
      if (error) throw new Error(`${error.code}: ${error.message}`);
      console.log(run.summary);
      console.log(run.markdown);
    }
    
    main();
    $npx tsx --env-file=.env scripts/conformance.ts ses_...
Live mode

Going live

In live mode the WebView has to load the acceptance page from your registered domain over HTTPS. Everything else is the usual four moves.

  1. 01
    Register your domainEnter your production host in the dashboard under Domains. Registering app.example.com covers example.com and every subdomain, and every plan, Free included, covers that one domain.
  2. 02
    Verify it with one TXT recordAdd a TXT record named _esigncomply with the value esc-verify=<token> that the dashboard shows. Esign Comply checks every minute for the first hour. Leave the record in place: it is checked again every day.
  3. 03
    Add your organization detailsEnter your organization's legal name and country in the dashboard. The Free plan covers 10 live signature events a month with no checkout. Starter is $200 per year for 2,000 live signature events, and Unlimited is $1,200 per year. One event is one signer's completed signing act, so the terms and the privacy notice accepted together at signup count once.
  4. 04
    Switch to the live keyCreate a live key (esc_live_...) and set it on your production server only. It never goes into the app bundle. Copy your documents and profile to live from the dashboard, set the live IDs beside the key, set APP_ORIGIN to your HTTPS origin and point SITE in the release build at the same origin.

In live mode context.url has to be inside your registered domain, browser calls are accepted only from it, and a finding at Block level stops the record from being sealed. Run the conformance check until nothing blocks before you switch keys.

Copy-paste prompt

Have your AI tool do it instead

Paste this into Cursor, Claude Code or any coding agent that is open on your app and your API. It tells the tool the one thing it will not guess: the acceptance screen is a page on your domain inside a WebView, not a native view.

The prompt generator writes the long version: your own document and profile IDs, the rule packs for your regions and the stack you pick, in one prompt.

Generate a prompt
Prompt: clickwrap in React Native
Add a signup clickwrap to this React Native app and its API server with Esign Comply. A new user accepts our Terms of Service and Privacy Notice before the account is created. Esign Comply observes the acceptance and keeps the independent record.

Read these first and follow them exactly:
- https://esigncomply.com/setup.md
- https://esigncomply.com/auth.md
- https://esigncomply.com/llms.txt
- https://esigncomply.com/guides/react-native-clickwrap (working code for this stack: use it as the reference)

Stack
- The browser SDK needs a DOM. Build the acceptance screen as a web page served from our own domain and show it with react-native-webview. Do not rebuild it as a native view, and do not look for an Esign Comply package for React Native: there is none.
- The page loads <script src="https://esigncomply.com/sdk/v1/esigncomply.js"></script> (global EsignComply).
- The secret key lives on the API server only (the esigncomply Node package). It never ships in the app.

Build
1. Server: a route creates the session with esc.sessions.create, with context.url set to the acceptance page, and returns only the client token, the API URL and the pinned documents. Save the signer ID and version IDs in an acceptances table.
2. Page: post "ready" to the app with window.ReactNativeWebView.postMessage. When the app calls window.startCeremony with the client token, attach, present each document link, observe our own unchecked checkbox and button, and call complete() from the user's real tap. Post the record ID back to the app.
3. App: render the WebView, pass the token in with injectJavaScript, and send the record ID to the server.
4. Server: before creating the account, read the record with esc.records.get and require status recorded, timestamped or anchored, the expected livemode, and the saved signer ID and version IDs. Store the record ID and the receipt.

Never
- Never invent API methods, packages or legal wording.
- Never pre-check the box, auto-submit or click for the user.
- Never put the secret key in client code, in a template or in the repository, and never print it.
- Never create the account before the server has confirmed the record.

If anything conflicts with existing code, stop and ask me.

Questions about a clickwrap in React Native

Can I add a clickwrap to a React Native app?

Yes. Show the acceptance screen in a WebView that loads a page from your own domain. The browser SDK runs in that page, observes your checkbox and button, and reports the ceremony straight to Esign Comply. The native app passes the client token in and receives the record ID back over the WebView message bridge, and your server confirms the record before it creates the account.

Why does the acceptance screen have to be a WebView?

Because the browser SDK works by observing real page elements: the notice text, the links, the checkbox and the button. A native view has no DOM for it to observe. In a WebView the SDK reports from the signer's device directly to Esign Comply, so the record is an independent observation of what was shown and what was tapped.

Can I build the acceptance screen as a fully native view instead?

Yes, with a different kind of record. Create the session with capture_mode set to server_only, and your server sends the ceremony events and the completion with the secret key. Every event in that record is tagged asserted, because Esign Comply did not observe the signer's device, and the evidence report says so. The WebView keeps the events tagged observed.

Read about server-only sessions

Is there an Esign Comply package for React Native?

No, and you do not need one. The app uses react-native-webview, the community WebView component, and plain fetch calls to your own API. The Esign Comply code runs in two places: the browser SDK in the page your WebView loads, and the esigncomply Node package on your server.

How do I test the WebView flow on a simulator or a phone?

Run your server on localhost:3000 and point the WebView at http://localhost:3000. The iOS simulator reaches it directly. On the Android emulator run adb reverse tcp:3000 tcp:3000 first. Test keys accept localhost, 127.0.0.1 and the hosts you list under Test origins, so a physical phone needs an HTTPS host that is on that list. A plain http address on your LAN does not work, because the SDK needs HTTPS or localhost.

Read about test mode

Put the acceptance page on your domain and the WebView in your app. Leave the record to us.

Free plan: 10 live signatures a month and a full test mode. No card required.

Working with an AI tool? This page is also available as Markdown: /guides/react-native-clickwrap.md