Skip to main content

Deeplinking Example

Exchanging Data Between Your Mobile App and Kukai-Embed​

To communicate with Kukai-Embed, your mobile app (iOS/Android/Unity) needs to send and receive deeplinks to and from a self-hosted web page. This web page allows users to sign in with a social provider, submit operations, and receive responses with more information regarding their actions (e.g. operation hashes, errors).


Implement a web page that handles deeplinks:​

  1. Clone our mobile app example repository
  2. Go to the /web-client folder and run yarn to install the dependencies (install yarn if it’s not available):
cd web-client && yarn
  1. Change the redirect deeplink URL to match a schema recognized by your app (see line):
App.tsx
const REDIRECT_DEEPLINK = `${YOUR_PROJECT_SCHEMA}://`;
  1. Run the project locally to verify that it works with your mobile app by using yarn dev (you can visit http://localhost:3000 for testing)
web-client/
yarn dev

  1. While kukai-embed is running locally, send a deeplink from your mobile app to localhost

    warning

    Simulators may not be able to access localhost. Use your private network address http://<ip>:<port> or ngrok if localhost is not available.

    • For social login:​

      http://localhost:3000/?action=login

      Once users have successfully signed in using a social provider, kukai-embed will send a deeplink back to your mobile app (see line)

      // send a deeplink that includes user information back to your mobile app
      window.location.href = encodeURI(
        `${REDIRECT_DEEPLINK}kukai-embed/?address=${pkh}&name=${name}&email=${email}&authResponse=${authResponse}&message=${message}&signature=${signature}&typeOfLogin=${userData.typeOfLogin}`
      );

    • For operations:​

      Send a deeplink from your mobile app to localhost, including the operation payload (stringified JSON) and optionally a typeOfLogin that was received from the previous deeplink. This will limit the social provider options, so that if users need to sign in again, they will only be presented with the social provider they initially selected:

      http://localhost:3000/?action=operation&typeOfLogin=<typeOfLogin>&operation=<payload>

      If the operation is injected successfully, kukai-embed will provide an operationHash. Send a deeplink back to your app (see line)

      window.location.href = encodeURI(
        `${REDIRECT_DEEPLINK}kukai-embed/?address=${pkh}&name=${name}&email=${email}&typeOfLogin=${typeOfLogin}&operationHash=${operationHash}`
      );

    • Handling errors:​

      In case of errors, operations will be rejected. Kukai-embed provides an errorMessage as well as a low-level errorId that you can map to more user-friendly error messages. You may choose to handle errors on the web page itself, potentially attempting a retry, or send the errors back to your mobile app with a deeplink (see example):

       window.location.href = encodeURI(`${REDIRECT_DEEPLINK}kukai-embed/?errorMessage=${error?.errorMessage}&errorId=${error?.errorId}`)

      For more information regarding error handling, please visit the Error Handling page

  2. Use yarn build to create a /build folder. You can upload this /build folder to a web hosting provider, such as Cloudflare Pages or Aws S3