Technical Reference
IDKit
IDKit is open source and accepts contributions! Head over to GitHub and submit a pull request.
Components
IDKitWidget
The IDKitWidget
component is the main component that renders the World ID widget. It should be mounted in your React app and passed the relevant parameters. Accepts a function as a child that receives a open
function to open the widget.
import { IDKitWidget } from '@worldcoin/idkit'
<IDKitWidget
app_id="app_GBkZ1KlVUdFTjeMXKlVUdFT" // obtained from the Developer Portal
action="vote_1" // this is your action name from the Developer Portal
signal="user_value" // any arbitrary value the user is committing to, e.g. a vote
onSuccess={onSuccess}
credential_types={['orb', 'phone']} // the credentials you want to accept
enableTelemetry
>
{({ open }) => <button onClick={open}>Verify with World ID</button>}
</IDKitWidget>
```
{/*
### `SignInWithWorldID`
The `SignInWithWorldID` component is a wrapper around the `IDKitWidget` component that renders the World ID widget with some parameters preset for Sign in with Worldcoin. Please see the [Sign In Widget page](/advanced/sign-in-widget) for usage details.
### `SignInButton`
The `SignInButton` component is a styled and animated button, used as the default for the [`SignInWithWorldID` component](/advanced/sign-in-widget). It is also exported separately for use with custom components. */}
## Parameters
The following parameters can be passed as props to the `IDKitWidget` component:
### Required
<Properties>
<Property name="app_id" type="string">
Unique identifier for the app verifying the action. This should be the App ID obtained from the [Developer
Portal](https://developer.worldcoin.org).
</Property>
<Property name="action" type="string">
Identifier for the action the user is performing. This should be the action name set in the Developer Portal.
</Property>
<Property name="onSuccess" type="function">
Function to trigger when verification is successful and the modal is closed. Should receive a single parameter of type `ISuccessResult`
which contains [the proof details.](#response)
</Property>
</Properties>
### Optional
<Properties>
<Property name="handleVerify" type="function">
Called after the proof is returned from the World App, but before showing the success screen. Throwing an error in this
screen will show the user a custom error. Used to perform additional validation when needed.
</Property>
<Property name="enableTelemetry" type="boolean">
Whether opt-in telemetry is enabled, defaults to `false`. Very few events are sent, with no PII to help improve the project. [Read more here.](/reference/idkit/telemetry)
</Property>
<Property name="theme" type='"light" | "dark"'>
The theme to apply to the widget's UI. Defaults to `light`.
</Property>
<Property name="signal" type="string">
For use when validating proofs on-chain. Read more on [the On-chain section](/advanced/on-chain).
</Property>
<Property name="action_description" type="string">
The description of the specific action (shown to users in World App). **Only used for Dynamic Actions.**
</Property>
<Property name="credential_types" type="string[]">
An array of credential types to allow for verification. Will accept any combination of `orb` & `phone`. Defaults
to `orb`. **TypeScript apps can use the `CredentialType` enum.**
</Property>
<Property name="autoClose" type="boolean">
Whether to automatically close the widget after completion. Defaults to `true`.
</Property>
</Properties>
## Hooks
### `useIDKit`
The `useIDKit` hook allows you to programmatically open the IDKit widget without mounting any buttons on screen. Note that you still need to mount the component for this to work.
```jsx focus=1,3,6,11
import { useIDKit } from '@worldcoin/idkit'
const { open, setOpen } = useIDKit()
useEffect(() => {
setOpen(true)
}, [])
return (
<div>
<IDKitWidget app_id="..." action="..." />
</div>
)
Methods
.init()
The .init()
method is the main initialization method used for vanilla JS apps. It should be called to start up IDKit and configure the widget.
.init(parameters) => void
Example:
idkit.init({
action: 'my_action',
app_id: 'app_lshSNnaJfdt6Sohu6YAA',
})
.open()
The .open()
method is used to open the widget. It should be called after the .init()
method.
Example:
idkit.open()
Response
Upon successful completion of the World ID flow, you will receive a response object. This response object of type ISuccessResult
has the following attributes. Normally, you will forward these parameters to your backend or smart contract for verification.
- Name
merkle_root
- Type
- string
- Description
This is the hash pointer to the root of the Merkle tree that proves membership of the user's identity in the list of identities verified by the Orb. ABI encoded.
- Name
nullifier_hash
- Type
- string
- Description
Essentially the user's unique identifier for your app (and specific action if using Anonymous actions). ABI encoded.
- Name
proof
- Type
- string
- Description
The Zero-knowledge proof of the verification. ABI encoded.
- Name
credential_type
- Type
- "orb" | "phone"
- Description
Either
orb
orphone
. Will always return the strongest credential with which a user has been verified.
Error Handling
Errors in the JS package will generally be returned in the Promise rejection of the .init()
method. In exceptional cases, some errors may be thrown in the Javascript console (though this is mostly for unhandled errors, and is not normal behavior).
The errorResult
object that is returned in the Promise rejection has the following structure:
{
"code": "already_signed",
"detail": "User has previously signed and submitted proof for this action."
}
If you enable telemetry, any errors will be reported to help proactively detect and fix any bugs. If you are running into an issue and don't have telemetry enabled, please report any bugs.
Error codes
The JS package may return any of the following error codes.
Code | Description | How to fix? |
---|---|---|
connection_failed | Could not establish a connection to the WLD app. | Ask the user to check their internet connection on both devices running your dapp and their WLD app. Additionally, make sure the user has the latest WLD app version. |
verification_rejected | User rejected the World ID request in their WLD app. | If this was a mistake, ask the user to go through the flow again. |
already_signed | This person has already submitted a proof for the particular action. | Nothing to do. User cannot submit a request for the same action twice. |
invalid_action_id | The action ID provided to IDKit is not valid. | Check the action ID. Make sure it's a valid string. |
invalid_signal | The signal provided to IDKit is not valid. | Check the signal. Make sure it's a valid string or address. |
unexpected_response | There was a problem with the response obtained from the WLD app. | Check the JS console for further details, though in most cases these will require contacting us to report the bug. |
generic_error | An unhandled exception occurred. | Check the JS console for further details, though in most cases these will require contacting us to report the bug. |
Telemetry
The Javascript package comes bundled with optional opt-in telemetry. Receiving these telemetry events from the package helps us understand how the product is being used so it can be improved.
- PII is not captured, neither from the developer, nor end users. Not even the IP address. It's all anonymous analytics.
- When a telemetry event is received, the IP address is used to obtain a rough location (country, state/province, city) using the MaxMind database through PostHog, the IP address is immediately discarded and not stored.
- Nothing is stored in the user's device running IDKit. No cookies, no local storage, nothing.
- No fingerprinting or any other mechanism to attempt to identify users cross-browser or cross-device.
- All telemetry events are captured using PostHog, an open-source product analytics library.
Events captured
Here are the events captured:
idkit loaded
. When the widget is loaded.idkit opened
. When IDKit is triggered in the user interface.$exception
. When an unhandled exception occurs in the package. The error message and the stack trace is included.
Attributes captured
For each event, the additional metadata is kept:
- Estimated coarse location, like country and state/province (from IP address). IP address is discarded.
- Screen size.
- IDKit version.
- Device information from
User-Agent
(e.g. browser, OS, ...). - Current URL.
- Referrer header.