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>

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