Customer Accounts

The Mobile Buy SDK provides support for letting customers create and log in to accounts on your shop. Being logged in allows customers to see their past orders, and streamlines the web checkout process, by using their existing address information.

For detailed examples of how to handle customer accounts, please see the customer sample app.

Signing up

Sign up requires using -createCustomerWithCredentials:callback: and providing the necessary sign up fields, specified using a credentials object. The customer is logged in automatically using a second endpoint request, if the creation succeeds. Therefore, the callbacks for both are the same.

// Create credential items with email, first name, last name, password, password confirmation
NSArray *items = @[[BUYAccountCredentialItem itemWithEmail:@"user@example.com"], [BUYAccountCredentialItem itemWithFirstName:@"Test"], ...];
BUYAccountCredentials *credentials = [BUYAccountCredentials credentialsWithItems:items];

// The customer will be retrieved automatically if the sign up was successful
[client createCustomerWithCredentials:credentials callback:(BUYCustomer *customer, NSString *token, NSError *error) {
        if (customer && !error) {
            // save the token to user defaults
        }
        else {
            // handle the error
        }
    }
}]

Logging in

Logging in is synonymous with creating a temporary authentication token. The token is used to verify access to protected customer data. Once the token is created, the BUYClient keeps a copy in memory, which it submits with every following request.

To authenticate, create the appropriate credentials using the email and password provided by the user, and invoke -loginCustomerWithCredentials:callback:.

// Create credential items with email and password
NSArray *items = @[[BUYAccountCredentialItem itemWithEmail:@"user@example.com"], [BUYAccountCredentialItem itemWithPassword:@"$3KretSozZ"]];
BUYAccountCredentials *credentials = [BUYAccountCredentials credentialsWithItems:items];

[client loginCustomerWithCredentials:credentials callback:(BUYCustomer *customer, NSString *token, NSError *error) {
        if (customer && !error) {
            // save the token to user defaults
        }
        else {
            // handle the error
        }
    }]

The callback will include a customer and a token. Save the token if you want to persist authenticated sessions across application launches. Remember to keep it private, and save it only in the user's keychain or similar secure location.

Ensuring the user stays logged in

You can delay the expiration of a login session by renewing the associated token. The value of the token may change, so be sure to refresh your stored version. You should renew the token periodically. A reasonable strategy is to renew every time the app becomes active.

[client renewCustomerTokenCallback:^(NSString *token, NSError *error) {
    if (token && !error) {
        // save the token to user defaults
    }
    else {
        // handle the error
    }
}]

Logging out

Logging out is synonymous with deleting the user's authentication token. You should always log out via the API when the user requests it.

If logout is successful, delete the token from any persistent storage, such as NSUserDefaults. The BUYClient will automatically delete its copy of the token. If logout fails, because the token has already expired, then this will not be reported as an error.

[client logoutCustomerCallback:(NSError *error) {
    if (error) {
        // handle error
    }
    else {
        // delete local in-memory and cached copies of the token, update UI
    }
}]

Customer activation

Customers that check out on the web and enable "remember my details" will have an account created automatically. They will receive an email from Shopify letting them know this. The email will include an account activation link. This link contains a token that you can use to activate their account with the API, if you implement support for universal links. (If you don't, the link will be handled by the user's web brower.)

You will need to extract the customer id and the activation token from the activation link URL, and pass those to the API. The customer will be logged in automatically.

[client activateCustomerWithCredentials:credentials customerID:customerID token:token callback:^(BUYCustomer *customer, BUYCustomerToken *token, NSError *error) {
    if (customer && !error) {
        // save the token to user defaults
    }
    else {
        // handle error
    }
}]