Migrating from v1 to v2 of Lock for iOS
Lock 2.0 is the latest major release of Lock iOS-OSX. This guide is provided in order to ease the transition of existing applications using Lock 1.x to the latest APIs.
- iOS 9.0+
- Xcode 8.0+
- Swift 3.0+
Lock v2 cannot be used from Objective-C, since its public API relies on Swift features and that makes them unavailable in ObjC codebases.
If you are willing to have some Swift code in your existing application, you can follow this guide on how to mix Objective-C and Swift and then use Lock v2 from the Swift files.
If that's not an option, we recommend sticking with Lock v1 or using Auth0.swift to build your own interface for user logins and signups.
Benefits of upgrading
- Complete Swift 3 Compatibility: The new version includes the adoption of the new API Design Guidelines.
- Improved UI: having a professional looking login box that displays well on any device.
- Extensive configuration: Lock provides improved configuration options to help customize the experience to your users needs.
- Safari controller for web-based Auth: Following Google's recent ban of WebView based auth, Lock (and Auth0.swift) will always use
SFSafariViewControllerwhen web auth is needed.
- API Authorization support: Adds support for Auth0 API Authorization
Changes from v1
Lock 2.0 has adopted to all of the new Swift 3 changes and conventions, including the new API Design Guidelines. Because of this, almost every API in Lock has been modified in some way. This guide will attempt to identify the most common usages and how they have changed, to help you get started with Lock 2.0. For yet more information on Lock 2.0, you can also see the Lock 2.0 Reference documentation.
Integration with your Application
Lock needs to be notified for some of your application state changes and some events/notifications your application receives from the OS. You can do all these things in the
Application finished launching
In Lock v1 you'd add the following:
In Lock v2, this is no longer required.
Application is asked to open URL
In Lock v1 you'd add the following:
In Lock v2 you need to instead use the following:
Application is asked to continue a User Activity
If you are using Lock passwordless and have specified the
.magicLink option to send the user a universal link then you will need to add the following to your
Lock by default will handle Email/Password, Enterprise & Social authentication based on your application's connections enabled in your Auth0 Dashboard under "Connections" in your application settings.
Like in v1, in your application bundle you can add a
plist file named
Auth0.plist with the following format:
This will load your Auth0 credentials.
In v1 to show Lock from a
UIViewController you'd add the following code:
In v2, to show Lock, the following code will be necessary:
So, in the
onAuth callback, you'd only receive the credentials of the user when the authentication is successful.
In the case you need to know about the errors or signup, there are the corresponding
onSignUp callbacks that can be employed.
Passwordless mode (Email & SMS connections)
In v1 to show Lock Passwordless from a
UIViewController you'd need to use either:
In V2 both email and sms now use the same method:
- Passwordless can only be used with a single connection and will prioritize the use of email connections over SMS.
audienceoption is not available in Passwordless.
If you needed to tweak Lock behaviour using its options in v1, you would use the following format:
In Lock v2 you can do it all before presenting Lock by using this format:
In v1 all UI customizations were performed using the
A0Theme object in this format:
In Lock v2, the UI customization is done using the
Use Auth0.Swift Library to access user profile
Lock can no longer directly access user profile information. To do so, you will now need to use the Auth0.Swift library. Below is an example of accessing
Delegation is not available through Lock. It can be implemented via a legacy method in Auth0.Swift for tenants which existed prior to June 2017.