Use deeplinking
Integrate Self protocol inside your mobile application using Deeplinking
⚠️ Breaking Changes:
SelfAppBuilder
is now imported from@selfxyz/qrcode
, not@selfxyz/core
New
disclosures
object is required to specify verification requirementsAdditional required parameters in the builder
Import getUniversalLink from @selfxyz/core
and SelfAppBuilder from @selfxyz/qrcode
:
import { getUniversalLink } from '@selfxyz/core';
import { SelfAppBuilder } from '@selfxyz/qrcode';
Instantiate your Self app using SelfAppBuilder with the required configuration:
const selfApp = new SelfAppBuilder({
appName: "Your App Name", // Required: Your application name
scope: "your-app-scope", // Required: Unique identifier for your app (max 31 chars)
endpoint: "https://your-api.com/verify", // Required: Your verification endpoint
logoBase64: "<base64-logo-or-png-url>", // Optional: Your app logo
userId: "user-uuid-or-address", // Required: User identifier
userIdType: 'uuid', // Optional: 'uuid' (default) or 'hex' for addresses
version: 2, // NEW in V2: Protocol version
userDefinedData: "0x" + Buffer.from("default").toString('hex').padEnd(128, '0'), // NEW in V2
disclosures: { // NEW: Specify what to verify
minimumAge: 18, // Age verification
excludedCountries: ['IRN', 'PRK'], // ISO 3-letter country codes to exclude
ofac: true, // OFAC sanctions check
name: true, // Request name disclosure
nationality: true, // Request nationality disclosure
date_of_birth: true, // Request date of birth
// ... other optional fields
}
}).build();
Get the deeplink from the Self app object:
const deeplink = getUniversalLink(selfApp);
You can now use this deeplink to redirect your users to the Self mobile app.
What's New in V2
Required Parameters
version: 2
- Specifies the protocol versionuserDefinedData
- 64-byte hex string for custom data passed to your backend
Disclosures Object
The disclosures
object allows you to specify what information you want to verify and request from the user's passport:
disclosures: {
// Identity fields (optional)
issuing_state?: boolean, // Country that issued the passport
name?: boolean, // Full name
passport_number?: boolean, // Passport number
nationality?: boolean, // Nationality
date_of_birth?: boolean, // Date of birth
gender?: boolean, // Gender
expiry_date?: boolean, // Passport expiry date
// Verification requirements (optional)
minimumAge?: number, // Minimum age requirement (e.g., 18, 21)
excludedCountries?: string[], // ISO 3-letter codes (e.g., ['IRN', 'PRK'])
ofac?: boolean, // Enable OFAC sanctions checking
}
User ID Types
When using blockchain addresses as user IDs:
// For Ethereum/blockchain addresses
const selfApp = new SelfAppBuilder({
// ... other config
userId: "0x1234567890abcdef...", // User's address
userIdType: 'hex', // Specify hex for addresses
}).build();
// For regular UUIDs
const selfApp = new SelfAppBuilder({
// ... other config
userId: "550e8400-e29b-41d4-a716-446655440000", // UUID v4
userIdType: 'uuid', // Default, can be omitted
}).build();
Important Notes
Endpoint Requirements:
For
endpointType: 'https'
(default), the endpoint must be publicly accessibleThe endpoint must start with
https://
Maximum length: 496 characters
Scope Limitations:
Must contain only ASCII characters
Maximum length: 31 characters
Should be unique to your application
V2 Parameters:
Always include
version: 2
for the latest protocoluserDefinedData
is a 64-byte hex string for passing custom data to your backendThis data is used by your
IConfigStorage
implementation to determine verification rules
Backend Coordination:
The
disclosures
object must match your backend verification configurationAny mismatch will cause verification failures
Migration from V1
If you're upgrading from V1, add these new parameters:
// V1 (old)
const selfApp = new SelfAppBuilder({
appName: "My App",
scope: "my-app",
endpoint: "https://api.myapp.com/verify",
userId: userId
}).build();
// V2 (new)
const selfApp = new SelfAppBuilder({
appName: "My App",
scope: "my-app",
endpoint: "https://api.myapp.com/verify",
userId: userId,
version: 2, // Add version
userDefinedData: "0x00...", // Add user defined data
disclosures: { /* ... */ } // Add disclosures
}).build();
Last updated