Migrate from 2.x to 3.0

Starting with TMG SDK 3.0.0, several public APIs are simplified.

Initialize the SDK

The SDK removes TMGClientConfiguration.Builder and moves configuration to the TMGClientConfiguration initializer:

• Removed: TMGClientConfiguration.Builder
• Use instead: TMGClientConfiguration

What changed

• Deprecated certificatePins. The SDK now manages certificate pinning internally.
• Renamed serverUrl to serverURL.
• Renamed serverKeyId to serverKeyID.

Before 3.0.0

let serverUrl;
let serverCertificate;
let keyIdentifier;
let configurationBuilder = TMGClientConfiguration.Builder(serverUrl: serverUrl, 
                                                          serverCertificate: Data(serverCertificate.utf8), 
                                                          serverKeyId: keyIdentifier)
let configuration: TMGClientConfiguration = TMGClientConfiguration(builder: configurationBuilder)

3.0.0

let serverURL = ""
let serverCertificate = ""
let serverKeyID = ""
let configuration = TMGClientConfiguration(serverURL: serverURL,
                                           serverCertificate: Data(serverCertificate.utf8),
                                           serverKeyID: serverKeyID)

Initialize VisaCTFHelper

In TMG SDK 3.0.0, createVisaCTFHelper changes from async to sync. This simplifies error handling and control flow.

Before 3.0.0

let tmgClient = TMGClient.sharedInstance
tmgClient.createVisaCTFHelper(tmgClientConfiguration: configuration,
                              completion: { (visaCTFHelper, error) in
  // Gets the VisaCTFHelper object
  // Checks the error
})

3.0.0

do {
    let visaCTFHelper = try TMGClient.sharedInstance.createVisaCTFHelper(withConfiguration: configuration)
} catch let error {
    // Handle the error
}

Update device binding flows (green and yellow)

Device binding covers device authentication, Identification and Verification (ID&V), and binding completion. In TMG SDK 3.0.0, the flow:

• Standardized the use of completionHandler.
• Removed the mix of delegate and completionHandler.
• Removed the need to handle binding success in multiple places.
• Streamlined control flow.

When migrating from earlier SDK versions, note these API renames:

• PendingBindingSession is now VisaCTFHelper.IDVSession.
• DeviceAuthenticationDelegate is now DeviceAuthentication.
• IdvMethod is now IDVMethod.
• IdvType is now IDVType.
• OtpActivationStatus is now OTPActivationStatus.

  • maxOtpRequestsAllowed is now maxOTPRequestsAllowed.
  • maxOtpVerificationAllowed is now maxOTPVerificationAllowed.

Use the code below to update your device binding integration:

Before 3.0.0

// 1. conform to DeviceAuthenticationDelegate (this is for device authentication)
class DeviceAuthenticationDelegateImplementation: DeviceAuthenticationDelegate {

    let authenticationMessage

    func shouldStartAuthentication(startHandler: (String?, Bool) -> Void) {
        //3. Start user authentication 
        startHandler(authenticationMessage, YES)
    }
}

var pendingBindingSession: PendingBindingSession?
let deviceId
let correlationId
let deviceAuthenticationDelegate = DeviceAuthenticationDelegateImplementation()
// 2. Start create binding
visaCTFHelper.createBinding(vProvisionedTokenId: vProvisionedTokenId,
                            correlationId: correlationId,
                            deviceAuthenticationDelegate: deviceAuthenticationDelegate) { session, error in
    // 4. Success bind [Scenario 1]
    if error == nil && session == nil {

    }
    // 5. Store locally session for yellow flow
    pendingBindingSession = session
}
// MARK: idv flow
// 6. Get list of idv methods (Yellow flow)
pendingBindingSession.idvMethods(completion: { idvMethods, error in
    if error == nil {
        let listOfIdvMethod = idvMethods
    }
})

//7. Submit selected idv method (OTP flow)
let selectedIdvMethod
pendingBindingSession.submitIdvMethod(idvMethod: selectedIdvMethod,
                                      completion: { otpActivationStatus, error in
     // Check no error
    if error == nil {
        let maxOtpVerificationAllowed = otpActivationStatus.maxOtpRequestsAllowed
        let maxOtpRequestsAllowed = otpActivationStatus.maxOtpVerificationAllowed
        let otpExpiration = otpActivationStatus.maxOtpVerificationAllowed
    }
    // 8. retry if error
    
})

//9. Activate binding
let otp
pendingBindingSession.activateBinding(otp: otp, 
                                      completion: { error in
    // 4.1 Success bind [Scenario 2]
    if error == nil {

    }
    // 10. Retry if error
})

3.0.0

// The singleton class to hold required properties for the visa flow
class VisaService {
    static var shared = VisaService()
    var idvSession: VisaCTFHelper.IDVSession? = nil
    var completionHandler: ((VisaCTFHelper.IDVSession?, TMGError?) -> Void)? = nil
}

let vProvisionedTokenID: String = ""
let correlationID: String = ""
// 1. Start create binding
visaCTFHelper.createBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            correlationID: correlationID,
    deviceAuthenticationHandler: { auth in
        // 2. Start user authentication
        let customMessage = "" // Pass in the custom message. e.g: "Authenticate with Face ID"
        auth.startAuthentication(withMessage: customMessage)
    }, idvSessionHandler: { session in
        // 3. Store locally session for yellow flow
        VisaService.shared.idvSession = session

    }, completionHandler: { session, error in
        // 4. hold the completion handler locally
        VisaService.shared.completionHandler?(session, error)
    })

// MARK: idv flow
do {
    guard let session = VisaService.shared.idvSession else {
        return
    }
    // 5. Get list of idv methods (Yellow flow)
    let idvMethods = try session.idvMethods
    // 6. Submit selected idv method (OTP flow)
    session.selectIDVMethod(idvMethods[0]) { otp in
        // Check otp activation status
    }
} catch let error {
    // error on list of idv methods
}

// 7. Activate Binding
let otp = ""
VisaService.shared.idvSession?.activateBinding(withValue: otp)

// 8. Handle success of error.
// You can listen to completionHandler for success or error
VisaService.shared.completionHandler = {(session, error) in
    // 9. Success bind
    if error == nil {
        
    } else if let error, let session {
        // 10. Retry if error
        if error.description == TMGError.invalidOTPMessage.description {
            VisaService.shared.idvSession = session
        }
    } else {
        // 11. Handle error
    }
}

Resume a binding (resumeBinding)

The resumeBinding flow is unchanged from earlier versions. Only the IDVSession (ID&V) steps change.

Before 3.0.0

var pendingBindingSession: PendingBindingSession?
// 1. Start resume binding
visaCTFHelper.resumeBinding(vProvisionedTokenId: vProvisionedTokenId) { session, error in
    // 2. Store locally session for yellow flow
    if error == nil { 
        pendingBindingSession = session
    }
    // Check error
}

// 3. MARK: idv flow (refer to create binding idv flow in code snippet)

3.0.0

// The singleton class to hold required properties for the visa flow
class VisaService {
    static var shared = VisaService()
    var idvSession: VisaCTFHelper.IDVSession? = nil
    var completionHandler: ((VisaCTFHelper.IDVSession?, TMGError?) -> Void)? = nil
}
let vProvisionedTokenID: String = ""
// 1. Start resume binding
visaCTFHelper.resumeBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            idvSessionHandler: { session in
        // 2. Store locally session for yellow flow
        VisaService.shared.idvSession = session        
    }, completionHandler: { session, error in
        // 3. hold the completion handler locally
        VisaService.shared.completionHandler?(session, error)
    })
// 4. MARK: idv flow (refer to create binding idv flow in code snippet)

Get the binding state (bindingState)

In TMG SDK 3.0.0, bindingState changes from async to sync. This simplifies error handling and control flow.

Before 3.0.0

let vProvisionedTokenId = ""
visaCTFHelper.bindingState(vProvisionedTokenId: vProvisionedTokenId) { (bindingState, error) in 
}

3.0.0

let vProvisionedTokenID = ""
do {
    let state = try visaCTFHelper.bindingState(forVProvisionedTokenID: vProvisionedTokenID)
} catch let error {
    // Handle the error
}

Authenticate a transaction

Transaction authentication covers device authentication and returning the Visa payload. In TMG SDK 3.0.0, the flow:

• Standardized the use of completionHandler.
• Removed the mix of delegate and completionHandler.

Use the code below to update your transaction authentication integration:

Before 3.0.0

// 1. conform to DeviceAuthenticationDelegate (this is for device authentication)
class DeviceAuthenticationDelegateImplementation: DeviceAuthenticationDelegate {

    let authenticationMessage

    func shouldStartAuthentication(startHandler: (String?, Bool) -> Void) {
        //3. Start user authentication 
        startHandler(authenticationMessage, YES)
    }
}

let deviceAuthenticationDelegate = DeviceAuthenticationDelegateImplementation()

// 2. Start authenticate transaction
visaCTFHelper.authenticateTransaction(vProvisionedTokenId: vProvisionedTokenID,
                                      deviceAuthenticationDelegate: deviceAuthenticationDelegate,
                                      completion: { visaPayload, error in
    // 4. Successfully generate payload
    if error == nil {
    
    } else {
        // Handle error
    } 
})

3.0.0

let vProvisionedTokenID: String = ""
        
// 1. Start authenticate transaction
visaCTFHelper.authenticateTransaction(forVProvisionedTokenID: vProvisionedTokenID,
                                        deviceAuthenticationHandler: { auth in
        // 2. Start user authentication 
        let customMessage = "" // Pass in the custom message. e.g: "Authenticate with Face ID"
        auth.startAuthentication(withMessage: customMessage)
    }, completionHandler: { (visaPayload, error) in
        // 3. Success generate payload
        if error == nil {
            
        } else {
            // Handle error
        }    
})

Remove a binding (removeBinding)

removeBinding now requires an additional correlationID.

Before 3.0.0

// 1. Start remove binding
visaCTFHelper.removeBinding(vProvisionedTokenId: vProvisionedTokenID,
                            completion: { error in
    // 2. Success remove binding
    if error == nil {
        
    } else {
        // Handle error
    }
})

3.0.0

let vProvisionedTokenID: String = ""
let correlationID: String = ""

// 1. Start remove binding
visaCTFHelper.removeBinding(forVProvisionedTokenID: vProvisionedTokenID,
                            correlationID: correlationID) { error in
    // 2. Success remove binding
    if error == nil {
        
    } else {
        // Handle error
    } 
}

Sync binding state (syncBindingState)

syncBindingState now requires an additional correlationID.

Before 3.0.0

// 1. Start sync binding state
visaCTFHelper.syncBindingState(vProvisionedTokenId: vProvisionedTokenID,
                               completion: { bindingState, error in
    // 2. Success sync binding state
    if error == nil {
        
    } else {
        // Handle error
    }  
})

3.0.0

let vProvisionedTokenID: String = ""
let correlationID: String = ""

// 1. Start sync binding state
visaCTFHelper.syncBindingState(forVProvisionedTokenID: vProvisionedTokenID,
                                correlationID: correlationID) { (state, error) in
    // 2. Success sync binding state
    if error == nil {
        
    } else {
        // Handle error
    }   
}

Read the previously selected ID&V method

In addition to the IDVSession functions used in the createBinding flow, you can read the previously selected ID&V method. In TMG SDK 3.0.0, previouslySelectedIDVMethod changes from async to sync. This simplifies error handling and control flow.

Before 3.0.0

// 1. Get previously selected idv method
pendingBindingSession.previouslySelectedIdvMethod(completion: { idvMethod, error in
    // 2. successfully get previously selected idv method
    if error == nil {
        let prevIDVMethod = idvMethod
    } else {
        // Handle error
    } 
})

3.0.0

guard let idvSession = VisaService.shared.idvSession else {
    // no idv session
    return
}
// 1. Get previously selected idv method
do {
    let prevIDVMethod = try idvSession.previouslySelectedIDVMethod
} catch let error {
    // 2. handle error
}