Giters

subdigital / Cely

Plug-n-Play login system for iOS written in Swift

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Swift 3.0 bitrise status Carthage compatible codecov

Prounounced Cell-Lee

Overview

Cely's goal is to add a login system into your app in under 30 seconds!

Background

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?

  1. Simple API to store user creditials and information securely
  • Cely.save("SUPER_SECRET_STRING", forKey: "token", securely: true)
  1. Manages switching between your app's Home Screen and Login Screen with:
  • Cely.changeStatus(to: .loggedIn) // or .loggedOut
  1. Customizable starter Login screen(or you can use your login screen)

What Cely does not do for you?

  1. Network requests
  2. Handle Network errors
  3. Anything with the network

Requirements

  • Xcode 8
  • swift 3.0

Installation

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

Usage

###Setup(30 seconds)

User Model (User.swift)

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

Hit RUN!!

CelyOptions

Handle Login Credentials

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
}

Customize Default Login Screen

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
}

Use your own Screens

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.

⚠️⚠️⚠️⚠️ Be sure to make your Login screen as the 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.

Variables

##### `store` A class that conforms to the [`CelyStorageProtocol`](#Cely.CelyStorageProtocol) protocol. By default is set to a singleton instance of `CelyStorage`.

Methods

##### `setup(with:forModel:requiredProperties:withOptions:)` Sets up Cely within your application
Example 
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.
##### `currentLoginStatus(requiredProperties:fromStorage:)` Will return the `CelyStatus` of the current user.
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
##### `get(_:fromStorage:)` Returns stored data for key.
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).
##### `save(_:forKey:toStorage:securely:persisted:)` Saves data in store
Example 
Cely.save("test@email.com", 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.
##### `changeStatus(to:)` Perform action like `LoggedIn` or `LoggedOut`.
Example 
changeStatus(to: .loggedOut)
Parameters
Key Type Required? Description
status CelyStatus ✅ enum value
##### `logout(usesStorage:)` Convenience method to logout user. Is equivalent to `changeStatus(to: .loggedOut)`
Example 
Cely.logout()
Parameters
Key Type Required? Description
store CelyStorage no Storage Cely will be using. Defaulted to CelyStorage.
##### `isLoggedIn()` Returns whether or not the user is logged in
Example 
Cely.isLoggedIn()
Returns
Type Description
Boolean Returns whether or not the user is logged in

Constants

Protocols

##### `CelyUser ` `protocol` for model class to implements
Required
value Type Description
Property associatedtype Enum of all the properties you would like to save for a model
##### `CelyStorageProtocol ` `protocol` a storage class must abide by in order for Cely to use it
Required 
func set(_ value: Any?, forKey key: String, securely secure: Bool, persisted: Bool) -> StorageResult
func get(_ key: String) -> Any?  
func removeAllData()
##### `CelyStyle` The `protocol` an object must conform to in order to customize Cely's default login screen. Since all methods are optional, Cely will use the default value for any unimplemented methods.
Methods 
func backgroundColor() -> UIColor
func textFieldBackgroundColor() -> UIColor
func buttonBackgroundColor() -> UIColor
func buttonTextColor() -> UIColor
func appLogo() -> UIImage?

Typealias

##### `CelyProperty ` `String` type alias. Is used in User model
##### `CelyCommands ` `String` type alias. Command for cely to execute

enums

##### `CelyOptions` `enum` Options that you can pass into Cely on [`setup(with:forModel:requiredProperties:withOptions:)`](#Cely.setup)
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
##### `CelyStatus` `enum` Statuses for Cely to perform actions on
Statuses
Case
loggedIn Indicates user is now logged in.
loggedOut Indicates user is now logged out.
##### `StorageResult ` `enum` result on whether or not Cely successfully saved your data.
Results
Case
success Successfully saved your data
fail(error) Failed to save data along with a LocksmithError.

License

Cely is available under the MIT license. See the LICENSE file for more info.

About

Plug-n-Play login system for iOS written in Swift

License:MIT License

Languages

Language:Swift 90.2%Language:C 8.6%Language:Objective-C 1.2%