Technical Reference

IDKit

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 for usage details.

SignInButton

The SignInButton component is a styled and animated button, used as the default for the SignInWithWorldID component. It is also exported separately for use with custom components.

Parameters

The following parameters can be passed as props to the IDKitWidget component:

Required

Optional

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.

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.

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."
}

Error codes

The JS package may return any of the following error codes.

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 we can improve it. Additionally, any bugs that are found are automatically detected so we can proactively work on fixing them.

• We don't capture any PII, neither from the developer, nor end users. Not even the IP address. It's all anonymous analytics.
• When a telemetry event is received, we use the IP address to obtain a rough location (country, state/province, city) using the MaxMind database through PostHog, the IP address is immediately discarded and not stored anywhere.
• We don't store anything on the device running the World ID widget. No cookies, no local storage, nothing.
• We don't do 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. We'll likely be looking into moving to our own self-hosted PostHog version in the future.

Events captured

Here are the events we capture:

• wid loaded. When the widget is loaded.
• wid opened. When the user clicks on the World ID widget and the modal shows up.
• wid connection established. When the connection to the user's WLD app is established. We include the number of seconds it took from the previous step.
• wid verification success. When the complete World ID process is successful.
• wid verification failed. When the complete World ID process fails. We include the errorCode here too.
• $exception. When an unhandled exception occurs in the package. We include the error message and the stack trace.

Attributes captured

For each event, we capture the following information:

• Estimate city location (from IP address). IP address is discarded.
• Screen size.
• World ID package version.
• Device information from User-Agent (e.g. browser, OS, ...).
• Current URL.
• Referrer header.