IIResidenceStore is my own implementation of TBUserIdentidy by @qnoid. I found his implementation to a bit confusing and wanted to take a more layered approach: make an api (
IIResidenceStore) and then some controllers and views on top of that.
That way, you'd be free on how to implement this yourself: create your own UI or use the default.
Create a store
You need an instance of
IIResidenceStore to interact with a residence store. A store needs a verifier website which implements the REST calls needed to verify residences.
IIResidenceStore* residenceStore = [IIResidenceStore storeWithVerifier:@"http://user-identity-nsconf.herokuapp.com/users"];
This creates a store backed by
Register a residence in the store (aka create new user)
Next, you need to register a residence with the verifier. You use the
registerResidenceForEmail:completion: call for that. This call will remember the email locally (this info is stored in the keychain).
This method takes an email address and a completion block:
- (void)registerResidenceForEmail:(NSString*)email completion:(void(^)(BOOL success, NSError* error))completion;
It will call the verifier, and register/create a new residence registration there. The verifier should send the user an email in which she can very the residence. The completion block is called when the request completes. This does not mean the address is verified! The completionblock will return
success if everything went ok.
error might contain more error information, but this is not necessarly the case.
Verify a residence
After the user has verified a residence request, the app should check if the verification was successfull. You use the
verifyResidenceForEmail:completion: method for that.
This method takes the same email address and another completion block:
- (void)verifyResidenceForEmail:(NSString*)email completion:(void(^)(BOOL success, NSError* error))completion;
It will check with the verifier if the email/residence has been verified by the user. It will return
success if that is the case.
error might contain more error information, but this is not necessarly the case. After you have successfully verified an email, you can use the other methods to get to information.
Check if an email is already registered:
This will return
YES if the email is registered. This does not check with the verifier, but just the local datastore. This will only return
YES if the registration call was succesfully in the past.
Check if an email is already verified:
This will return
YES if the email is registered and verified. This does not check with the verifier, but just the local datastore. This will only return
YES if both the registration and verification calls were succesfully in the past.
Get the residence token:
Returns the residence token supplied by the verification call for an email address. This will return
nil if the residence was not registered or verified. You can use this token to authorize api calls or whatever.
Get all local emails:
Returns a list of local stored emails. These are both unregistered, registered, unverified and verified addresses. You can use the state calls above to check which can be used.
Remove all local residence information:
This clears the local information from the keychain.
@property (nonatomic, strong, readonly) NSString* verifier;
This returns the address of the verifier of the current store.
@property (nonatomic, assign) NSTimeInterval verifierTimeout;
Specifies a timeout value for the calls to the verifier. This defaults to 30 seconds.
Keep in mind
Email adresses are case-insensitive.
email@example.com will be the same as
Verifier endpoint addresses are case-sensitive. This is important because:
Residence info is stored in the keychain. This means it cannot be read by other applications. Each store's info is stored separately. This also means that the information will live on even if you delete and reinstall the app. The information will not persist in backups (since we assume that another device is another residence).
This thing requires ARC and a fairly recent version of Xcode (4.6 or so). It only runs on iOS6 or higher.
Don't forget to reference the
IIResidenceStore published under the MIT license:
Copyright (C) 2013, Tom Adriaenssen
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.