This quickstart guide will walk you through implementing a complete MetaMap verification flow in your iOS app using UIKit.
Prerequisites
Before starting, ensure you have:
Completed the Installation guide
Your MetaMap Client ID from the dashboard
Your Flow ID for the verification flow you want to use
Required permissions configured in Info.plist
Implementation Steps
Import MetaMap SDK
Open your ViewController.swift file and import the MetaMap SDK: import UIKit
import MetaMapSDK
Setup MetaMap Button
Create and configure the MetaMap button in your view controller. Add this code to your ViewController class: class ViewController : UIViewController {
override func viewDidLoad () {
super . viewDidLoad ()
self . setupMetaMapButton ()
}
private func setupMetaMapButton () {
// Initialize the MetaMap button
let metaMapButton = MetaMapButton ()
// Add button action
metaMapButton. addTarget (
self ,
action : #selector ( self . metaMapButtonAction ),
for : . touchUpInside
)
// Configure button layout
metaMapButton. frame = CGRect (
x : 20 ,
y : self . view . frame . size . height / 2 - 50 ,
width : view. frame . size . width - 40 ,
height : 50
)
// Add button to view
view. addSubview (metaMapButton)
// Set delegate to receive verification results
MetaMapButtonResult. shared . delegate = self
}
}
The MetaMapButton comes with default MetaMap branding. You can customize its appearance using metadata (see Customization below).
Launch Verification Flow
Add the action handler that launches the MetaMap verification flow when the button is tapped: @objc private func metaMapButtonAction () {
// Launch MetaMap verification flow
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [ "key1" : "value1" , "key2" : 123 ]
)
}
Replace YOUR_CLIENT_ID and YOUR_FLOW_ID with your actual credentials from the MetaMap dashboard.
Handle Verification Results
Implement the MetaMapButtonResultDelegate to handle verification callbacks: // MARK: - MetaMapButtonResultDelegate
extension ViewController : MetaMapButtonResultDelegate {
func verificationSuccess ( identityId : String ? , verificationID : String ? ) {
print ( "MetaMap Verification Success" )
print ( "Identity ID: \( identityId ?? "N/A" ) " )
print ( "Verification ID: \( verificationID ?? "N/A" ) " )
// Handle successful verification
// Example: Navigate to next screen, update UI, send to backend
}
func verificationCancelled () {
print ( "MetaMap Verification Cancelled" )
// Handle cancellation
// Example: Show message to user, log analytics event
}
}
Store the identityId and verificationID to check verification status on your backend or query the MetaMap API.
Complete Example
Here’s the complete working implementation:
import UIKit
import MetaMapSDK
class ViewController : UIViewController {
override func viewDidLoad () {
super . viewDidLoad ()
self . setupMetaMapButton ()
}
private func setupMetaMapButton () {
// Init button
let metaMapButton = MetaMapButton ()
// Add button action
metaMapButton. addTarget (
self ,
action : #selector ( self . metaMapButtonAction ),
for : . touchUpInside
)
// Set view of button
metaMapButton. frame = CGRect (
x : 20 ,
y : self . view . frame . size . height / 2 - 50 ,
width : view. frame . size . width - 40 ,
height : 50
)
// Add button to your view
view. addSubview (metaMapButton)
// Set delegate to get result
MetaMapButtonResult. shared . delegate = self
}
@objc private func metaMapButtonAction () {
// Set params to showMetaMapFlow
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [ "key1" : "value1" , "key2" : 123 ]
)
}
}
// MARK: - MetaMapButtonResultDelegate
extension ViewController : MetaMapButtonResultDelegate {
func verificationSuccess ( identityId : String ? , verificationID : String ? ) {
print ( "MetaMap Verification Success \( identityId ?? "" ) " )
}
func verificationCancelled () {
print ( "MetaMap Verification Cancelled" )
}
}
Customization
The metadata parameter allows you to customize the SDK behavior and appearance:
Set Language
By default, the SDK uses English. You can set a fixed language:
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [ "fixedLanguage" : "es" ] // Spanish
)
Supported languages: en, es, fr, pt, ru, tr, de, it, pl, th
Customize the button appearance to match your app’s design:
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [
"buttonColor" : "#FF5733" , // Background color (hex)
"buttonTextColor" : "#FFFFFF" // Text color (hex)
]
)
Re-verification Flow
For returning users, pass their existing identity ID:
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [ "identityId" : "existing-identity-id" ]
)
Enable Encryption
For enhanced security, use an encryption configuration:
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [ "encryptionConfigurationId" : "your-config-id" ]
)
Custom Fonts
Use your app’s custom fonts (ensure font files are included in your project):
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [
"regularFont" : "CustomFont-Regular.ttf" ,
"boldFont" : "CustomFont-Bold.ttf"
]
)
Testing Your Integration
Build and Run
Build and run your app on a physical iOS device (camera access is limited in simulator): # Select your device in Xcode, then:
# Product > Run (⌘ + R)
Grant Permissions
When prompted, allow camera, photo library, and microphone access.
Complete Verification
Tap the MetaMap button and complete the verification flow:
Follow the on-screen instructions
Capture required documents
Complete liveness check
Confirm submission
Check Results
Verify that your delegate methods are called:
Check console logs for success/cancellation messages
Verify you receive identityId and verificationID
Test on Physical Device : The verification flow requires camera access, which is not fully functional in the iOS Simulator. Always test on a real device.
Here’s a comprehensive example with multiple metadata options:
MetaMap. shared . showMetaMapFlow (
clientId : "YOUR_CLIENT_ID" ,
flowId : "YOUR_FLOW_ID" ,
metadata : [
"fixedLanguage" : "en" ,
"buttonColor" : "#007AFF" ,
"buttonTextColor" : "#FFFFFF" ,
"identityId" : "optional-existing-id" ,
"encryptionConfigurationId" : "optional-encryption-id" ,
"regularFont" : "AppFont-Regular.ttf" ,
"boldFont" : "AppFont-Bold.ttf" ,
"userId" : "your-internal-user-id" ,
"customParam" : "any-custom-value"
]
)
Next Steps
SwiftUI Integration Learn how to integrate with SwiftUI
Advanced Configuration Explore advanced SDK configuration options
Handle Results Learn how to process verification results
API Reference View complete API documentation