Prounounced Cell-Lee
Cely's goal is to add a login system into your app in under 30 seconds!
Whether you're building an app for a client or for a hackathon, building a login system, no matter how basic it is, can be very tedious and time-consuming. Cely's architecture has been battle tested on countless apps, and Cely guarantees you a fully functional login system in a fraction of the time. You can trust Cely is handling login credentials correctly as well since Cely is built on top of Locksmith, swift's most popular Keychain wrapper.
###Details: What does Cely does for you?
- Simple API to store user creditials and information securely
Cely.save("SUPER_SECRET_STRING", forKey: "token", securely: true)
- Manages switching between your app's Home Screen and Login Screen with:
Cely.changeStatus(to: .loggedIn) // or .loggedOut
- Customizable starter Login screen(or you can use your login screen)
What Cely does not do for you?
- Network requests
- Handle Network errors
- Anything with the network
- Xcode 8
- swift 3.0
###Carthage
github "ChaiOne/Cely"
Cely will also include Locksmith when you import it into your project, so be sure to add Locksmith in your copy phase script.
$(SRCROOT)/Carthage/Build/iOS/Cely.framework
$(SRCROOT)/Carthage/Build/iOS/Locksmith.framework
####Keychain entitlement Part(Xcode 8 bug?) Be sure to turn on Keychain entitlements for your app, not doing so will prevent Cely from saving data to the keychain.
###Setup(30 seconds)
Let's start by creating a User model that conforms to the CelyUser Protocol:
// User.swift
import Cely
struct User: CelyUser {
enum Property: CelyProperty {
case token = "token"
}
}####Login redirect(AppDelegate.swift)
Cely's Simple Setup function will get you up and running in a matter of seconds. Inside of your AppDelegate.swift simply import Cely and call the setup(_:) function inside of your didFinishLaunchingWithOptions method.
// AppDelegate.swift
import Cely
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: Any]?) -> Bool {
Cely.setup(with: window, forModel: User(), requiredProperties: [.token])
...
}Now how do we get the username and password from Cely's default LoginViewController? It's easy, just pass in a completion block for the .loginCompletionBlock. Check out CelyOptions for more info.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
Cely.setup(with: window!, forModel: User(), requiredProperties: [.token], withOptions: [
.loginCompletionBlock: { (username: String, password: String) in
if username == "asdf" && password == "asdf" {
Cely.save(username, forKey: "username")
Cely.save("FAKETOKEN:\(username)\(password)", forKey: "token", securely: true)
Cely.changeStatus(to: .loggedIn)
}
}
])
return true
}Create an object that conforms to the CelyStyle protocol and set it to .loginStyle inside of the CelyOptions dictionary when calling Cely's setup(_:) method.
// LoginStyles.swift
struct CottonCandy: CelyStyle {
func backgroundColor() -> UIColor {
return UIColor(red: 86/255, green: 203/255, blue: 249/255, alpha: 1) // Changing Color
}
func buttonTextColor() -> UIColor {
return .white
}
func buttonBackgroundColor() -> UIColor {
return UIColor(red: 253/255, green: 108/255, blue: 179/255, alpha: 1) // Changing Color
}
func textFieldBackgroundColor() -> UIColor {
return UIColor.white.withAlphaComponent(0.4)
}
func appLogo() -> UIImage? {
return UIImage(named: "CelyLogo")
}
}
...
// AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
Cely.setup(with: window!, forModel: User.ref, requiredProperties: [.token], withOptions: [
.loginStyle: CottonCandy(), // <--- HERE!!
.loginCompletionBlock: { ... }
])
return true
}To use your own login screen, simply create a storyboard that contains your login screen and pass that in as .loginStoryboard inside of the CelyOptions dictionary when calling Cely's setup(_:) method.
Lastly, if your app uses a different storyboard other than Main.storyboard, you can pass that in as .homeStoryboard.
InitialViewController inside of your storyboard!
// AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
Cely.setup(with: window!, forModel: User.ref, requiredProperties: [.token], withOptions: [
.loginStoryboard: UIStoryboard(name: "MyCustomLogin", bundle: nil),
.homeStoryboard: UIStoryboard(name: "NonMain", bundle: nil)
])
return true
}###Recommended User Pattern
import Cely
struct User: CelyUser {
enum Property: CelyProperty {
case username = "username"
case email = "email"
case token = "token"
func securely() -> Bool {
switch self {
case .token:
return true
default:
return false
}
}
func persisted() -> Bool {
switch self {
case .username:
return true
default:
return false
}
}
func save(_ value: Any) {
Cely.save(value, forKey: rawValue, securely: securely(), persisted: persisted())
}
func get() -> Any? {
return Cely.get(key: rawValue)
}
}
}
// MARK: - Save/Get User Properties
extension User {
static func save(_ value: Any, as property: Property) {
property.save(value: value)
}
static func save(_ data: [Property : Any]) {
data.forEach { property, value in
property.save(value)
}
}
static func get(_ property: Property) -> Any? {
return property.get()
}
}The reason for this pattern is to make saving data as easy as:
// Pseudo network code, NOT REAL CODE!!!
ApiManager.logUserIn("username", "password") { json in
let apiToken = json["token"].string
// REAL CODE!!!
User.save(apiToken, as: .token)
}and getting data as simple as:
let token = User.get(.token)##API
###Cely Cely was made to help handle user credentials and handling login with ease. Below you will find documentation for Cely's Framework. Please do not hesitate to open an issue if something is unclear or is missing.
##### `store` A class that conforms to the [`CelyStorageProtocol`](#Cely.CelyStorageProtocol) protocol. By default is set to a singleton instance of `CelyStorage`. ##### `setup(with:forModel:requiredProperties:withOptions:)` Sets up Cely within your applicationExample
Cely.setup(with: window, forModel: User(), requiredProperties:[.token])
// or
Cely.setup(with: window, forModel: User(), requiredProperties:[.token], withOptions:[
.loginStoryboard: UIStoryboard(name: "MyCustomLogin", bundle: nil),
.HomeStoryboard: UIStoryboard(name: "My_NonMain_Storyboard", bundle: nil),
.loginCompletionBlock: { (username: String, password: String) in
if username == "asdf" && password == "asdf" {
print("username: \(username): password: \(password)")
}
}
])Parameters
| Key | Type | Required? | Description |
|---|---|---|---|
window |
UIWindow |
✅ | window of your application. |
forModel |
CelyUser |
✅ | The model Cely will be using to store data. |
requiredProperties |
[CelyProperty] |
no | The properties that cely tests against to determine if a user is logged in. Default value: empty array. |
options |
[CelyOption] |
no | An array of CelyOptions to pass in additional customizations to cely. |
Example
let status = Cely.currentLoginStatus()Parameters
| Key | Type | Required? | Description |
|---|---|---|---|
properties |
[CelyProperty] |
no | Array of required properties that need to be in store. |
store |
CelyStorage |
no | Storage Cely will be using. Defaulted to CelyStorage |
Returns
| Type | Description |
|---|---|
CelyStatus |
If requiredProperties are all in store, it will return .loggedIn, else .loggedOut |
Example
let username = Cely.get(key: "username")Parameters
| Key | Type | Required? | Description |
|---|---|---|---|
key |
String | ✅ | The key to the value you want to retrieve. |
store |
CelyStorage | no | Storage Cely will be using. Defaulted to CelyStorage |
Returns
| Type | Description |
|---|---|
Any? |
Returns an Any? object in the case the value nil(not found). |
Example
Cely.save("[email protected]", forKey: "email")
Cely.save("testUsername", forKey: "username", persisted: true)
Cely.save("token123", forKey: "token", securely: true)Parameters
| Key | Type | Required? | Description |
|---|---|---|---|
value |
Any? |
✅ | The value you want to save to storage. |
key |
String |
✅ | The key to the value you want to save. |
store |
CelyStorage |
no | Storage Cely will be using. Defaulted to CelyStorage. |
secure |
Boolean |
no | If you want to store the value securely. |
persisted |
Boolean |
no | Keep data after logout. |
Returns
| Type | Description |
|---|---|
StorageResult |
Whether or not your value was successfully set. |
Example
changeStatus(to: .loggedOut)Parameters
| Key | Type | Required? | Description |
|---|---|---|---|
status |
CelyStatus |
✅ | enum value |
Example
Cely.logout()Parameters
| Key | Type | Required? | Description |
|---|---|---|---|
store |
CelyStorage |
no | Storage Cely will be using. Defaulted to CelyStorage. |
Example
Cely.isLoggedIn()Returns
| Type | Description |
|---|---|
Boolean |
Returns whether or not the user is logged in |
Required
| value | Type | Description |
|---|---|---|
Property |
associatedtype |
Enum of all the properties you would like to save for a model |
Required
func set(_ value: Any?, forKey key: String, securely secure: Bool, persisted: Bool) -> StorageResult
func get(_ key: String) -> Any?
func removeAllData() Methods
func backgroundColor() -> UIColor
func textFieldBackgroundColor() -> UIColor
func buttonBackgroundColor() -> UIColor
func buttonTextColor() -> UIColor
func appLogo() -> UIImage?Options
| Case | |
|---|---|
storage |
Pass in you're own storage class if you wish not to use Cely's default storage. Class must conform to the CelyStorage protocol. |
homeStoryboard |
Pass in your app's default storyboard if it is not named "Main" |
loginStoryboard |
Pass in your own login storyboard. |
loginStyle |
Pass in an object that conforms to CelyStyle to customize the default login screen. |
loginCompletionBlock |
(String,String) -> Void block of code that will run once the Login button is pressed on Cely's default login Controller |
Statuses
| Case | |
|---|---|
loggedIn |
Indicates user is now logged in. |
loggedOut |
Indicates user is now logged out. |
Results
| Case | |
|---|---|
success |
Successfully saved your data |
fail(error) |
Failed to save data along with a LocksmithError. |
Cely is available under the MIT license. See the LICENSE file for more info.