Migrating tokens to system accounts

Updated on Tue, 2013-10-08 16:10

Overview

It is very common for applications to have previously verified and stored Twitter users' access tokens, either through an existing iOS application or via a server-side integration. Thankfully, it is easy to migrate these access tokens to the device so that you can take advantage of the tools the framework gives you. This document details that process.

Requirements

This process requires an application running on iOS5+, as well as verified access tokens and secrets for a Twitter user. Also, the target application must link against the Accounts.framework.

Code Example

For this example, consider the scenario where you have already verified and securely stored your user's access token and secret in an iOS application using xAuth, and would now like to migrate these tokens to the central account store.

Step 1: Add the necessary frameworks to your project

The process for adding the Social framework is detailed in Adding the Social framework. Follow the same instructions for adding Accounts.framework to your project's target. Also, ensure that you have added the following statement to include the framework:

#import <Accounts/Accounts.h>

Step 2: Add the migration code

The code that transitions tokens to the account store is quite simple, but you should should check for and gracefully handle any error conditions that may arise.

Note: For testing purposes, you can obtain verified tokens to use to validate this process by visiting http://dev.twitter.com/apps, and by viewing the bottom of an application page under the section entitled 'Your Access Token'.

Source Code Notes: This example utilizes Automatic Reference Counting (ARC); extraneous line breaks are added for clarity.

- (void)storeAccountWithAccessToken:(NSString *)token

                             secret:(NSString *)secret

```
{
```

  // Each account has a credential, which is comprised of a verified token

```
  //  and secret
```
```
 
```
```
  ACAccountCredential *credential =
```

    [[ACAccountCredential alloc] initWithOAuthToken:token

                                        tokenSecret:secret];

```
 
```

  //  Obtain the Twitter account type from the store

```
  ACAccountType *twitterAcctType =
```

    [_store accountTypeWithAccountTypeIdentifier:

```
      ACAccountTypeIdentifierTwitter];
```
```
 
```

  //  Create a new account of the intended type

```
  ACAccount *newAccount =
```

    [[ACAccount alloc] initWithAccountType:twitterAcctType];

```
 
```

  //  Attach the credential for this user

```
  newAccount.credential = credential;
```
```
 
```

  // Finally, ask the account store instance to save the account Note: that

  // the completion handler is not guaranteed to be executed on any thread,

  // so care should be taken if you wish to update the UI, etc.

```
 
```

  [_store saveAccount:newAccount withCompletionHandler:

```
    ^(BOOL success, NSError *error) {
```
```
    if (success) {
```
```
      // we've stored the account!
```
```
      NSLog(@"the account was saved!");
```
```
    }
```
```
    else {
```

      //something went wrong, check value of error

      NSLog(@"the account was NOT saved");

```
 
```

      // see the note below regarding errors...

      //  this is only for demonstration purposes

      if ([[error domain] isEqualToString:ACErrorDomain]) {

```
 
```

        // The following error codes and descriptions are found in ACError.h

```
        switch ([error code]) {
```

          case ACErrorAccountMissingRequiredProperty:

            NSLog(@"Account wasn't saved because "

                "it is missing a required property.");

```
            break;
```

          case ACErrorAccountAuthenticationFailed:

            NSLog(@"Account wasn't saved because "

                "authentication of the supplied "

```
                "credential failed.");
```
```
            break;
```

          case ACErrorAccountTypeInvalid:

            NSLog(@"Account wasn't saved because "

                "the account type is invalid.");

```
            break;
```

          case ACErrorAccountAlreadyExists:

            NSLog(@"Account wasn't added because "

```
                "it already exists.");
```
```
            break;
```
```
          case ACErrorAccountNotFound:
```

            NSLog(@"Account wasn't deleted because"

                "it could not be found.");

```
            break;
```
```
          case ACErrorPermissionDenied:
```

            NSLog(@"Permission Denied");

```
            break;
```
```
          case ACErrorUnknown:
```

          default: // fall through for any unknown errors...

            NSLog(@"An unknown error occurred.");

```
            break;
```
```
        }
```
```
      } else {
```

        // handle other error domains and their associated response codes...

        NSLog(@"%@", [error localizedDescription]);

```
      }
```
```
    }
```
```
  }];
```
```
}
```

Error conditions

For the official iOS overview that describes how to handle error conditions, please review the Error Handling Programming Guide in the Apple Developer Library.

If the token migration process is unsuccessful, there are two common error domains that may be returned: ACErrorDomain and NSURLErrorDomain . As demonstrated above, a simple switch statement can help explain any errors related to the storage of accounts, such as ACErrorAccountAlreadyExists, which indicates that you are attempting to store an account that has already been stored.

The Account Store must verify the credentials it is provided by communicating with Twitter, so it is possible that the error returned is in the NSURLErrorDomain. Like all network connectivity errors, these conditions should be gracefully handled in your application. For more information on the various error codes returned in the NSURLErrorDomain, please review the contents of NSURLError.h.

Next Steps

Once you have migrated your user's tokens to core account instances, you should review API requests with SLRequest.