Swiftpack.co - twilio/twilio-verify-ios as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by twilio.
twilio/twilio-verify-ios 1.3.0
Twilio Verify Push SDK helps you verify users by adding a low-friction, secure, cost-effective, "push verification" factor into your own apps. This project provides an SDK to implement Verify Push for your iOS app.
⭐️ 8
🕓 2 days ago
iOS
.package(url: "https://github.com/twilio/twilio-verify-ios.git", from: "1.3.0")

Twilio Verify iOS

CircleCI CocoaPods Compatible Carthage Compatible Swift Package Manager Compatible Platform Swift 5.2 License

Table of Contents

About

Twilio Verify Push SDK helps you verify users by adding a low-friction, secure, cost-effective, "push verification" factor into your own mobile application. This fully managed API service allows you to seamlessly verify users in-app via a secure channel, without the risks, hassles or costs of One-Time Passcodes (OTPs). This project provides an SDK to implement Verify Push for your iOS app.

Dependencies

None

Requirements

  • iOS 10+
  • Swift 5.2
  • Xcode 12.x

Documentation

SDK API docs

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate TwilioVerify into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'TwilioVerify', '~> 1.3.0'

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate TwilioVerify into your Xcode project using Carthage, specify it in your Cartfile:

github "twilio/twilio-verify-ios" -> 1.3.0

Since version 1.3.0 of TwilioVerifySDK the prebuilt asset fat version .framework is been deprecated, to give space for the universal framework .xcframework. Make sure to use the new version of Carthage 0.38.0 that was release in order to support the xcframework assets, by using this version or a superior one, Carthage will download and unzip the TwilioVerifySDK.framework.zip attached in the release version, resulting in a TwilioVerifySDK.xcframework that can be found in the build folder of Carthage.

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. It is in early development, but TwilioVerify does support its use on iOS.

Once you have your Swift package set up, adding TwilioVerify as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/twilio/twilio-verify-ios.git", .upToNextMajor(from: "1.3.0"))
]

Register Your App with APNs

If you want to receive challenges as push notifications, you should register Your App with APNs. More info here

Usage


NOTE

The SDK should be used from a Swift class. See an example in the TwilioVerifyAdapter class

Since version 1.3.0, the target was changed from TwilioVerify to TwilioVerifySDK. Migrating from older versions will imply to update all the imports in your files, see an example in the TwilioVerifyAdapter class


See Verify Push Quickstart for a step-by-step guide to using this SDK in a basic Verify Push implementation.

Running the Sample app

To run the Sample App:

  • Clone the repo
  • Change the Bundle Identifier to something unique so Apple’s push notification server can direct pushes to this app
  • Enable push notifications
  • Get the Access token generation URL from your backend (Running the Sample backend). You will use it for creating a factor
  • Run the TwilioVerifyDemo project using Release as build configuration

Silently approve challenges

You can silently approve challenges when your app already knows that the user is trying to complete an action (actively logging in, making a transaction, etc.) on the same device as the registered device that is being challenged.

You can enable the option "Silently approve challenges" for a factor. After enabling it, every challenge received as a push notification when the app is in foreground for that factor will be silently approved, so user interaction is not required. The option will be saved for the session, so the selection will not be persisted.

Running the Sample backend

Using the sample app

Adding a factor

  • Press Create factor in the factor list (click on the +, top right)
  • Enter the identity to use. This value should be an UUID that identifies the user to prevent PII information use
  • Enter the Access token URL (Access token generation URL, including the path, e.g. https://verify-push-backend-xxxxx.twil.io/access-token)
  • Press Create factor
  • Copy the factor Sid

Sending a challenge

  • Go to Create Push Challenge page (/challenge path in your sample backend)
  • Enter the identity you used in factor creation
  • Enter the Factor Sid you added
  • Enter a message. You will see the message in the push notification and in the challenge view
  • Enter details to the challenge. You will see them in the challenge view. You can add more details using the Add more Details button
  • Press Create challenge button
  • You will receive a push notification showing the challenge message in your device.
  • The app will show the challenge info below the factor information, in a Challenge section
  • Approve or deny the challenge
  • After the challenge is updated, you will see the challenge status in the backend's Create Push Challenge view

Logging

By default, logging is disabled. To enable it you can either set your own logging services by implementing LoggerService and calling addLoggingService (note that you can add as many logging services as you like) or enable the default logger service by calling enableDefaultLoggingService. Your multiple implementations and the default one can work at the same time, but you may just want to have it enabled during the development process, it's risky to have it turned on when releasing your app.

Setting Log Level

You may want to log only certain processes that are happening in the SDK, or you just want to log it all, for that the SDK allows you to set a log level.

  • error: reports behaviors that shouldn't be happening.
  • info: warns specific information of what is being done.
  • debug: detailed information.
  • networking: specific data for the networking work, such as request body, headers, response code, response body.
  • all: error, info, debug and networking are enabled.

Usage

To start logging, enable the default logging service or/and pass your custom implementations

var builder = TwilioVerifyBuilder()
#if DEBUG
  builder = builder.enableDefaultLoggingService(withLevel: .all)
                   .addLoggingService(MyOwnLoggerService1())
                   .addLoggingService(MyOwnLoggerService2())
#endif
twilioVerify = try builder.build()

Errors

Types Code Description
Network 60401 Exception while calling the API
Mapping 60402 Exception while mapping an entity
Storage 60403 Exception while storing/loading an entity
Input 60404 Exception while loading input
Key Storage 60405 Exception while storing/loading key pairs
Initialization 60406 Exception while initializing an object
Authentication Token 60407 Exception while generating token

Update factor's push token

You can update the factor's push token in case it changed, calling the TwilioVerify.updateFactor method:

let updateFactorPayload = UpdatePushFactorPayload(sid: factorSid, pushToken: newPushToken)
twilioVerify.updateFactor(withPayload: payload, success: { factor in
  // Success
}) { error in
  // Error
}

See FactorListPresenter in the sample app. You should update the push token for all factors.

Delete a factor

You can delete a factor calling the TwilioVerify.deleteFactor method:

twilioVerify.deleteFactor(withSid: factorSid, success: {
  // Success
}) { error in
  // Error
}

Clear local storage

You can clear the local storage calling the TwilioVerify.clearLocalStorage method:

do {
  try twilioVerify.clearLocalStorage()
} catch {
  // Handle error
}

Important Notes

  • Calling this method will not delete factors in Verify Push API, so you need to delete them from your backend to prevent invalid/deleted factors when getting factors for an identity.
  • Since the Keychain is used for storage this method can fail if there is an error while doing the Keychain operation.

Reinstall and persist factors

By default, the created factors and key pairs will not persist in the device after the app is uninstalled and reinstalled for security reasons. However, it's possible to change this default behavior and persist the factors and key pairs after a reinstall, because both are saved in the keychain.


NOTE This may change in future iOS versions, but it will keep working for iOS 15 and below. Preserving keychain items on app uninstall could be a security concern. You should not rely on this behaviour and provide an alternative way to enroll the factor again if this behaviour changes.


To persist factors after a reinstall, use TwilioVerifyBuilder.setClearStorageOnReinstall method when creating the TwilioVerify instance. The default value is true, so the factors will be deleted on reinstall. Change it to false to persist the factor(s)

let builder = TwilioVerifyBuilder().setClearStorageOnReinstall(false)
let twilioVerify = try builder.build()

The push token will change after the reinstall. Update the push token to receive push notifications for challenges, as is explained in Update factor's push token

The SDK is using kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly to save factors and keypairs. According to Apple,

Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

GitHub

link
Stars: 8
Last commit: 2 days ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

1.3.0
2 days ago

1.3.0 (2021-11-30)

Features

  • Support notification platform "none" to allow not sending push token. Factors with notification platform "none" will not receive push notifications for challenges and polling should be implemented to get pending challenges (e40a267)

Documentation

  • Update documentation to use new sample backend (bae60b8)
  • Improve persisting factors after a reinstall documentation (#166) (df16896)

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics