Quickstart

Complete guide to implement MetaMap iOS SDK verification flow in your application

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

1. Import MetaMap SDK

   Open your ViewController.swift file and import the MetaMap SDK:

   ViewController.swift

   import UIKit
   import MetaMapSDK
   
2. Setup MetaMap Button

   Create and configure the MetaMap button in your view controller. Add this code to your ViewController class:

   ViewController.swift

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

3. Launch Verification Flow

   Add the action handler that launches the MetaMap verification flow when the button is tapped:

   ViewController.swift

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

4. Handle Verification Results

   Implement the MetaMapButtonResultDelegate to handle verification callbacks:

   ViewController.swift

   // 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:

ViewController.swift

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 Button Colors

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

1. 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)
   
2. Grant Permissions

   When prompted, allow camera, photo library, and microphone access.

3. Complete Verification

   Tap the MetaMap button and complete the verification flow:

   • Follow the on-screen instructions
   • Capture required documents
   • Complete liveness check
   • Confirm submission
4. 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.

Common Metadata Options

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