Developer Guide for iOS
BioID Facial Recognition App
Welcome to the facial recognition app developer guide. The BioID app can communicate with your app or your website to provide your users the security and convenience of biometric authentication.
You have the following options to integrate with our app:
- In one app by integrating our app source code directly into your own app
- Using our app as a 'face authenticator' by communicating with our app via inter-app communication, either using our identity management via standard protocols, or your own via our BioID Web Service
Launching BioID app
The BioID facial recognition app uses standard iOS inter-app communication via a custom URL scheme
(see Apple specification).
In order for your iOS app to open the BioID app, you must create a correctly formatted URL and call the
openURL: method of the app object.
BioID app implements bioid-enroll and bioid-verify url schemes. More url schemes are already available - please contact us!
To enroll a user biometrically:
// Call the BioID app from your iOS app use the following command [[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"bioid-enroll://?access_token=YourBWSToken&return_url=YourApp&state=YourDefinition"]; // Call the BioID app from your website use the following as URL scheme bioid-enroll://?access_token=YourBWSToken&return_url=YourApp&state=YourDefinition
To verify a user biometrically:
// Call the BioID app from your iOS app use the following command [[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"bioid-verify://?access_token=YourBWSToken&return_url=YourApp&state=YourDefinition"]; // Call the BioID app from your website use the following as URL scheme bioid-verify://?access_token=YourBWSToken&return_url=YourApp&state=YourDefinition
- Required. A BWS web token that has previously been issued by the Token Extension.
- Required. A URL to redirect the user to your app after the biometric operation has been carried out. Please take a look at Using URL Schemes to Communicate with Apps.
- Recommended. Client specific data to maintain state between request and callback. For example you might want to add some information about the user you are verifying.
A. Do you want to use BioID as your identity provider?
If you want to use BioID as an identity provider (information like username, password, email address etc. stored by BioID) then BioID Connect is the right choice. The integration is easy, especially if you already support OpenID Connect or OAuth 2.0. Currently the service is available free of charge.
In the future we may charge for the service or limit the number of transactions.
A.1 Get a Client ID
To connect with the app using BioID Connect requires a client ID and client secret. If you already registered in the app, simply use the account you created. If you do not yet have a BioID account you will first need to register. Then go to your profile and select Client Developer to register a new client ID. You will then receive your client ID and secret.
A.2 Set up BioID Connect
Please see our BioID Connect developer page for more details on our OAuth 2.0 and OpenID Connect implementation.
A.3 User registration and enrollment
Your end users install the BioID app and sign up for a BioID account; they will then be prompted to enroll their biometrics.
B. Do you want to use your own identity management?
If you want to use your own identity management you can enhance your app to use BioID Web Service directly. In this case your users cannot be enrolled through the app. You must enroll them through a separate channel, for instance on your website using our Unified User Interface.
The biometric data is stored anonymously with no other personally identifiable information such as a name or email address.
B.1 Request a trial instance of BioID Web Service (BWS)
At BioID Playground you can apply for a trial instance of the BioID Web Service. After the trial instance has been set up you can continue to create and configure your BWS client application.
B.2 Register a BWS client application
Create and configure your BWS client application on BWS Management. Go to Client Apps section and click the Register a new Client App button. In the dialog window the client app identifier and secret is shown. Both values are required for your app later on (the real data replacing the placeholder text for CLIENT_APP_ID and CLIENT_APP_SECRET constants in sample code below).
The Credentials pane shows the name for your BWS instance in section BWS Client Configuration as well as other information needed for the user BCIDs.
Take a look at the BWS URL for the example
https://bws.bioid.com (BWS-Installation Multitenant). In this case the BWS instance name is
This would replace the dummy text for the BWS_INSTANCE_NAME constant in the sample code below then.
For the creation of BCIDs for users in your app the following information is needed
ClassID – this is a unique number you assign to the user, e.g.
4711. The BCID with the example values from above is
bws.12.4711. This value consisting from the three parts storage, partition and ClassID
separated by a period ('.') would replace the dummy text for the BCID constant in the sample code.
For more information about BCID take a look at Biometric Class ID.
Now you have all necessary data to call BWS!
B.3 User registration and enrollment
When you use the app with your own identity management, the app simply provides a pass-through function for enrollment and verification using the BWS token you provide, and ignores the BioID account (if any) registered to the user's device.