LeanStorage Objective-C Guide

The LeanStorage Objective-C SDK can be used to persist and query data in LeanCloud. The code below shows how you can create an object and store it into the cloud:

// Create an object
AVObject *todo = [AVObject objectWithClassName:@"Todo"];

// Set values of fields
[todo setObject:@"R&D Weekly Meeting"        forKey:@"title"];
[todo setObject:@"All team members, Tue 2pm" forKey:@"content"];

// Save the object to the cloud
[todo saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        // Execute any logic that should take place after the object is saved
        NSLog(@"Object saved. objectId: %@", todo.objectId);
    } else {
        // Execute any logic that should take place if the save fails
    }
}];

Getting Started

Installing SDK

The easiest way to integrate our SDK in your project is to use CocoaPods. Add the following pods into the Podfile under the project's root directory:

pod 'AVOSCloud'   # LeanStorage, SMS, In-App Socializing, LeanEngine
pod 'AVOSCloudIM' # LeanMessage

If you plan to use LiveQuery, add the following pod as well:

pod 'AVOSCloudLiveQuery'

After adding the pods, run pod install under the same directory to finish installing SDK.

Initializing Your Project

Import the basic modules into AppDelegate:

#import <AVOSCloud/AVOSCloud.h>

Then paste the following code into the application:didFinishLaunchingWithOptions: method:

[AVOSCloud setApplicationId:@"{{appid}}" clientKey:@"{{appkey}}"];

Debugging

You can easily trace the problems in your project by turning debug logs on during the development phase. Once enabled, details of every request made by the SDK along with errors will be output to IDE, browser console, or your app's Dashboard > LeanEngine > App logs.

// Place the line after [AVOSCloud setApplicationId:]; only needs to be called once
[AVOSCloud setAllLogsEnabled:YES];

Objects

AVObject

Storing data on LeanCloud is built around AVObject. Each AVObject contains key-value pairs of JSON-compatible data. This data is schema free, which means that you don't need to specify ahead of time what keys exist on each AVObject. Simply set whatever key-value pairs you want, and our backend will store it.

For example, the AVObject storing a simple todo item may contain the following data:

title:      "Email Linda to Confirm Appointment",
isComplete: false,
priority:   2,
tags:       ["work", "sales"]

Data Types

AVObject supports a wide range of data types to be used for each field, including common ones like String, Number, Boolean, Object, Array, Date, and null. You can nest objects in JSON format to store more structured data within a single Object or Array field.

Special data types supported by AVObject include Pointer and File, which are used to store a reference to another AVObject and binary data respectively.

AVObject also supports GeoPoint, a special data type you can use to store location-based data. See GeoPoints for more details.

Some examples:

// Basic objects
NSNumber     *boolean    = @(YES);
NSNumber     *number     = [NSNumber numberWithInt:2018];
NSString     *string     = [NSString stringWithFormat:@"%@ Top Hit Songs", number];
NSDate       *date       = [NSDate date];
NSData       *data       = [@"Hello world!" dataUsingEncoding:NSUTF8StringEncoding];
NSArray      *array      = [NSArray arrayWithObjects: string, number, nil];
NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys: number, @"number", string, @"string", nil];

// Create an object
AVObject *testObject = [AVObject objectWithClassName:@"TestObject"];
[testObject setObject:boolean    forKey:@"testBoolean"];
[testObject setObject:number     forKey:@"testInteger"];
[testObject setObject:string     forKey:@"testString"];
[testObject setObject:date       forKey:@"testDate"];
[testObject setObject:data       forKey:@"testData"];
[testObject setObject:array      forKey:@"testArray"];
[testObject setObject:dictionary forKey:@"testDictionary"];
[testObject saveInBackground];

We do not recommend storing large pieces of binary data like images or documents with AVObject using NSData. The size of each AVObject should not exceed 128 kilobytes. We recommend using AVFile for storing images, documents, and other types of files. To do so, create AVFile objects and assign them to fields of AVObject. See Files for details.

To learn about how you can protect the data stored on LeanCloud, see Data and Security.

Creating Objects

The code below creates a new instance of AVObject with class Todo:

AVObject *todo = [AVObject objectWithClassName:@"Todo"];

// You can also use this equivalent way
AVObject *todo = [[AVObject alloc] initWithClassName:@"Todo"];

The constructor takes class name as a parameter so that the cloud knows the class you are using to create the object. A class in LeanCloud is comparable to a table in a relational database. A class name starts with a letter and can only contain numbers, letters, and underscores.

Saving Objects

The following code saves a new object with class Todo to the cloud:

// Create an object
AVObject *todo = [AVObject objectWithClassName:@"Todo"];

// Set values of fields
[todo setObject:@"Sign up for Marathon" forKey:@"title"];
[todo setObject:@2 forKey:@"priority"];

// Save the object to the cloud
[todo saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        // Execute any logic that should take place after the object is saved
        NSLog(@"Object saved. objectId: %@", todo.objectId);
    } else {
        // Execute any logic that should take place if the save fails
    }
}];

To make sure the object is successfully saved, take a look at Dashboard > LeanStorage > Data > Todo in your app. You should see a new entry of data with something like this when you click on its objectId:

{
  "title":     "Sign up for Marathon",
  "priority":  2,
  "ACL": {
    "*": {
      "read":  true,
      "write": true
    }
  },
  "objectId":  "582570f38ac247004f39c24b",
  "createdAt": "2017-11-11T07:19:15.549Z",
  "updatedAt": "2017-11-11T07:19:15.549Z"
}

There are several built-in fields that are provided by default which you don't need to specify in your code:

Built-in Field	Type	Description
objectId	NSString	A unique identifier for each saved object.
ACL	AVACL	Access Control List, a special object defining the read and write permissions of other people.
createdAt	NSDate	The time the object was created.
updatedAt	NSDate	The time the object was last modified.

Each of these fields is filled in by the cloud automatically and doesn't exist on the local AVObject until a save operation has been completed.

Field names, or keys, can only contain letters, numbers, and underscores. A custom key can neither start with double underscores __, nor be identical to any system reserved words or built-in field names (ACL, className, createdAt, objectId, and updatedAt) regardless of letter cases.

Values can be strings, numbers, booleans, or even arrays and dictionaries — anything that can be JSON-encoded. See Data Types for more information.

We recommend that you adopt CamelCase naming convention to NameYourClassesLikeThis and nameYourKeysLikeThis, which keeps your code more readable.

Retrieving Objects

If AVObject is already in the cloud, you can retrieve it using its objectId with the following code:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query getObjectInBackgroundWithId:@"582570f38ac247004f39c24b" block:^(AVObject *todo, NSError *error) {
    // todo is the instance of the Todo object with objectId 582570f38ac247004f39c24b
    NSString *title    = todo[@"title"];
    int priority       = [[todo objectForKey:@"priority"] intValue];

    // Acquire special properties
    NSString *objectId = todo.objectId;
    NSDate *updatedAt  = todo.updatedAt;
    NSDate *createdAt  = todo.createdAt;
}];

If you try to access a field or property that doesn't exist, the SDK will not raise an error. Instead, it will return nil.

Refreshing Objects

If you need to refresh a local object with the latest version of it in the cloud, call the fetchInBackgroundWithBlock method on it:

AVObject *todo = [AVObject objectWithClassName:@"Todo" objectId:@"582570f38ac247004f39c24b"];
[todo fetchInBackgroundWithBlock:^(AVObject *todo, NSError *error) {
    // todo is refreshed
}];

Keep in mind that any unsaved changes made to the object prior to calling fetchInBackgroundWithBlock will be discarded. To avoid this, you have the option to provide a list of keys when calling the method so that only the fields being specified are retrieved and refreshed (including special built-in fields such as objectId, createdAt, and updatedAt). Changes made to other fields will remain intact.

AVObject *todo = [AVObject objectWithClassName:@"Todo" objectId:@"582570f38ac247004f39c24b"];
NSArray *keys = [NSArray arrayWithObjects:@"priority", @"location", nil];
[todo fetchInBackgroundWithKeys:keys block:^(AVObject *todo, NSError *error) {
    // Only priority and location will be retrieved and refreshed
}];

Updating Objects

To update an existing object, assign the new data to each field and call the saveInBackground method. For example:

AVObject *todo = [AVObject objectWithClassName:@"Todo" objectId:@"582570f38ac247004f39c24b"];
[todo setObject:@"Weekly meeting has been rescheduled to Wed 3pm for this week." forKey:@"content"];
[todo saveInBackground];

LeanCloud automatically figures out which data has changed and only the fields with changes will be sent to the cloud. The fields you didn't update will remain intact.

Updating Data Conditionally

By passing in a query option when saving, you can specify conditions on the save operation so that the object can be updated atomically only when those conditions are met. If no object matches the conditions, the cloud will return error 305 to indicate that there was no update taking place.

For example, in the class Account there is a field called balance, and there are multiple incoming requests that want to modify this field. Since an account cannot have a negative balance, we can only allow a request to update the balance when the amount requested is lower than or equal to the balance:

AVObject *account = [AVObject objectWithClassName:@"Account" objectId:@"5745557f71cfe40068c6abe0"];
// Atomically decrease balance by 100
NSInteger amount = -100;
[account incrementKey:@"balance" byAmount:@(amount)];
// Add the condition
AVQuery *query = [[AVQuery alloc] init];
[query whereKey:@"balance" greaterThanOrEqualTo:@(-amount)];
AVSaveOption *option = [[AVSaveOption alloc] init];
option.query = query;
// Return the latest data in the cloud upon completion.
// All the fields will be returned if the object is new,
// otherwise only fields with changes will be returned.
option.fetchWhenSave = YES;
[account saveInBackgroundWithOption:option block:^(BOOL succeeded, NSError * _Nullable error) {
    if (succeeded) {
        NSLog(@"Balance: %@", account[@"balance"]);
    } else if (error.code == 305) {
        NSLog(@"Insufficient balance. Operation failed!");
    }
}];

query option only works for existing objects. In other words, it has no effect on objects that haven't been saved to the cloud yet.

The benefit of using query option instead of combining AVQuery and AVObject shows up when you have multiple clients trying to update the same field at the same time. The latter way is more cumbersome and may lead to potential inconsistencies.

Updating Counters

Take Twitter as an example, we need to keep track of how many Likes and Retweets a tweet has gained so far. Since a Like or Retweet action can be triggered simultaneously by multiple clients, saving objects with updated values directly can lead to inaccurate results. To make sure that the total number is stored correctly, LeanCloud allows you to atomically increase (or decrease) the value of a number field:

[post incrementKey:@"likes" byAmount:@1];

You can specify the amount of increment (or decrement) by providing an additional argument. If the argument is not provided, 1 is used by default.

Updating Arrays

There are several operations that can be used to atomically update an array associated with a given key:

• addObject:forKey:
  appends the given object to the end of an array.
• addObjectsFromArray:forKey:
  appends the given array of objects to the end of an array.
• addUniqueObject:forKey:
  appends the given object to the end of an array ensuring that the object only appears once within the array.
• addUniqueObjectsFromArray:forKey:
  appends the given array of objects to the end of an array ensuring that each object only appears once within the array.
• removeObject:forKey:
  removes all instances of the given object from an array.
• removeObjectsInArray:forKey:
  removes all instances of the given array of objects from an array.

For example, Todo has a field named alarms for keeping track of times at which a user wants to be alerted. The following code adds the times to the alarms field:

-(NSDate*) getDateWithDateString:(NSString*) dateString{
    NSDateFormatter *dateFormat = [[NSDateFormatter alloc] init];
    [dateFormat setDateFormat:@"yyyy-MM-dd HH:mm:ss"];
    NSDate *date = [dateFormat dateFromString:dateString];
    return date;
}

NSDate *alarm1 = [self getDateWithDateString:@"2018-04-30 07:10:00"];
NSDate *alarm2 = [self getDateWithDateString:@"2018-04-30 07:20:00"];
NSDate *alarm3 = [self getDateWithDateString:@"2018-04-30 07:30:00"];

NSArray *alarms = [NSArray arrayWithObjects:alarm1, alarm2, alarm3, nil];

AVObject *todo = [AVObject objectWithClassName:@"Todo"];
[todo addUniqueObjectsFromArray:alarms forKey:@"alarms"];
[todo saveInBackground];

Deleting Objects

The following code deletes a Todo object from the cloud:

AVObject *todo = [AVObject objectWithClassName:@"Todo" objectId:@"582570f38ac247004f39c24b"];
[todo deleteInBackground];

Batch Processing

You can create, save, delete, or fetch multiple objects within a single request:

// Batch create and update
+ (BOOL)saveAll:(NSArray *)objects error:(NSError **)error;
+ (void)saveAllInBackground:(NSArray *)objects
                      block:(AVBooleanResultBlock)block;

// Batch delete
+ (BOOL)deleteAll:(NSArray *)objects error:(NSError **)error;
+ (void)deleteAllInBackground:(NSArray *)objects
                        block:(AVBooleanResultBlock)block;

// Batch fetch
+ (BOOL)fetchAll:(NSArray *)objects error:(NSError **)error;
+ (void)fetchAllInBackground:(NSArray *)objects
                       block:(AVArrayResultBlock)block;

The following code sets isComplete of all Todo objects to be true:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query findObjectsInBackgroundWithBlock:^(NSArray *todos, NSError *error) {
    // Get a collection of todos to work on
    for (AVObject *todo in todos) {
        // Update value
        todo[@"isComplete"] = @(YES);
    }
    // Save all at once
    [AVObject saveAllInBackground:todos];
}];

Although each function call sends multiple operations in one single network request, saving operations and fetching operations are billed as separate API calls for each object in the collection, while deleting operations are billed as a single API call.

Data Models

Objects may have relationships with other objects. For example, in a blogging application, a Post object may have relationships with many Comment objects. LeanCloud supports three kinds of relationships, including one-to-one, one-to-many, and many-to-many.

One-to-One and One-to-Many Relationships

One-to-one and one-to-many relationships are modeled by saving AVObject as a value in the other object. For example, each Comment in a blogging app might correspond to one Post.

The following code creates a new Post with a single Comment:

// Create a post
AVObject *post = [[AVObject alloc] initWithClassName:@"Post"];
[post setObject:@"I am starving!" forKey:@"title"];
[post setObject:@"Hmmm, where should I go for lunch?" forKey:@"content"];

// Create a comment
AVObject *comment = [[AVObject alloc] initWithClassName:@"Comment"];
[comment setObject:@"KFC is the best!" forKey:@"content"];

// Add the post as a property of the comment
[comment setObject:post forKey:@"parent"];

// This will save both post and comment
[comment saveInBackground];

Internally, the backend will store the referred-to object with the Pointer type in just one place in order to maintain consistency. You can also link objects using their objectIds like this:

AVObject *post = [AVObject objectWithClassName:@"Post" objectId:@"57328ca079bc44005c2472d0"];
[comment setObject:post forKey:@"post"];

See Relational Queries for instructions on how to query relational data.

Many-to-Many Relationships

The easiest way to model many-to-many relationships is to use arrays. In most cases, using arrays helps you reduce the number of queries you need to make and leads to a better performance. However, if additional properties need to be attached to the relationships between two classes, using join tables would be a better choice. Keep in mind that the additional properties are used to describe the relationships between classes rather than any single class.

We recommend you to use join tables if the total amount of objects of any class exceeds 100.

Queries

We've already seen how you can retrieve a single object from the cloud with AVObject, but it doesn't seem to be powerful enough when you need to retrieve multiple objects that match certain conditions at once. In such situation, AVQuery would be a more efficient tool you can use.

Basic Queries

The general steps of performing a basic query include:

1. Creating AVQuery.
2. Putting conditions on it.
3. Retrieving an array of objects matching the conditions.

The code below retrieves all Student objects whose lastName is Smith:

AVQuery *query = [AVQuery queryWithClassName:@"Student"];
[query whereKey:@"lastName" equalTo:@"Smith"];
[query findObjectsInBackgroundWithBlock:^(NSArray *students, NSError *error) {
    // students is an array of Student objects satisfying conditions
}];

Query Constraints

There are several ways to put constraints on the objects found by AVObject.

The code below filters out objects with Jack as firstName:

[query whereKey:@"firstName" notEqualTo:@"Jack"];

For sortable types like numbers and strings, you can use comparisons in queries:

// Restricts to age < 18
[query whereKey:@"age" lessThan:@18];

// Restricts to age <= 18
[query whereKey:@"age" lessThanOrEqualTo:@18];

// Restricts to age > 18
[query whereKey:@"age" greaterThan:@18];

// Restricts to age >= 18
[query whereKey:@"age" greaterThanOrEqualTo:@18];

You can apply multiple constraints to a single query, and objects will only be in the results if they match all of the constraints. In other words, it's like concatenating constraints with AND:

[query whereKey:@"firstName" equalTo:@"Jack"];
[query whereKey:@"age" greaterThan:@18];

You can limit the number of results by setting limit (defaults to 100):

// Limit to at most 10 results
query.limit = 10;

If you need exactly one result, you may use getFirstObject for convenience:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query whereKey:@"priority" equalTo:@2];
[query getFirstObjectInBackgroundWithBlock:^(AVObject *todo, NSError *error) {
    // todo is the first Todo object satisfying conditions
}];

You can skip certain number of results by setting skip:

// Skip the first 20 results
query.skip = 20;

You can implement pagination in your app by using skip together with limit:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query whereKey:@"priority" equalTo:@2];
query.limit = 10;
query.skip = 20;

For sortable types, you can control the order in which results are returned:

// Sorts the results in ascending order by the createdAt property
[query orderByAscending:@"createdAt"];

// Sorts the results in descending order by the createdAt property
[query orderByDescending:@"createdAt"];

You can even attach multiple sorting rules to a single query:

[query addAscendingOrder:@"priority"];
[query addDescendingOrder:@"createdAt"];

To retrieve objects that have or do not have particular fields:

// Finds objects that have the "images" field
[query whereKeyExists:@"images"];

// Finds objects that don't have the "images" field
[query whereKeyDoesNotExist:@"images"];

You can restrict the fields returned by providing a list of keys with selectKeys. The code below retrieves todos with only the title and content fields (and also special built-in fields such as objectId, createdAt, and updatedAt):

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query selectKeys:@[@"title", @"content"]];
[query getFirstObjectInBackgroundWithBlock:^(AVObject *todo, NSError *error) {
    NSString *title = todo[@"title"]; // √
    NSString *content = todo[@"content"]; // √
    NSString *notes = todo[@"notes"]; // An error will occur
}];

The unselected fields can be fetched later with fetchInBackgroundWithBlock. See Refreshing Objects.

Queries on String Values

Use hasPrefix to restrict to string values that start with a particular string. Similar to a LIKE operator in SQL, it is indexed so it is efficient for large datasets:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
// SQL equivalent: title LIKE 'lunch%'
[query whereKey:@"title" hasPrefix:@"lunch"];

Use containsString to restrict to string values that contain a particular string:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
// SQL equivalent: title LIKE '%lunch%'
[query whereKey:@"title" containsString:@"lunch"];

Unlike hasPrefix, containsString can't take advantage of indexes, which is not encouraged to be used for large datasets.

If you are looking for string values that do not contain a particular string, use matchesRegex with regular expressions:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
// "title" without "ticket" (case-insensitive)
[query whereKey:@"title" matchesRegex:@"^((?!ticket).)*$"];    

However, performing queries with regular expressions as constraints can be very expensive, especially for classes with over 100,000 records. The reason behind is that queries like this can't take advantage of indexes and will lead to exhaustive scanning of the whole dataset to find the matching objects. We recommend that you take a look at our In-App Searching feature, a full-text search solution we provide to improve your app's searching ability and user experience.

Queries on Array Values

The code below looks for all the objects with work as an element of its array field tags:

[query whereKey:@"tags" equalTo:@"work"];

You can also look for objects whose array field tags contains work, sales, and appointment:

[query whereKey:@"tags" containsAllObjectsInArray:[NSArray arrayWithObjects:@"work", @"sales", @"appointment", nil]];

To retrieve objects whose field matches any one of the values in a given list, you can use containedIn instead of performing multiple queries. The code below constructs a query that retrieves todo items with priority to be 1 or 2:

// Single query
AVQuery *priorityOneOrTwo = [AVQuery queryWithClassName:@"Todo"];
[priorityOneOrTwo whereKey:@"priority" containedIn:[NSArray arrayWithObjects:@1, @2, nil]];
// Mission completed :)

// ---------------
//       vs.
// ---------------

// Multiple queries
AVQuery *priorityOne = [AVQuery queryWithClassName:@"Todo"];
[priorityOne whereKey:@"priority" equalTo:@1];

AVQuery *priorityTwo = [AVQuery queryWithClassName:@"Todo"];
[priorityTwo whereKey:@"priority" equalTo:@2];

AVQuery *priorityOneOrTwo = [AVQuery orQueryWithSubqueries:[NSArray arrayWithObjects:priorityOne, priorityTwo, nil]];
// Kind of verbose :(

Conversely, you can use notContainedIn if you want to retrieve objects that do not match any of the values in a list.

Relational Queries

There are several ways to perform queries for relational data. To retrieve objects whose given field matches a particular AVObject, you can use equalTo just like how you use it for other data types. For example, if each Comment has a Post object in its post field, you can fetch all the comments for a particular Post with the following code:

AVObject *post = [AVObject objectWithClassName:@"Post" objectId:@"57328ca079bc44005c2472d0"];
AVQuery *query = [AVQuery queryWithClassName:@"Comment"];
[query whereKey:@"post" equalTo:post];
[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments contains the comments for the post
}];

To retrieve objects whose given field contains AVObject that matches a different query, you can use matchesQuery. The code below constructs a query that looks for all the comments for posts with images:

AVQuery *innerQuery = [AVQuery queryWithClassName:@"Post"];
[innerQuery whereKeyExists:@"images"];

AVQuery *query = [AVQuery queryWithClassName:@"Comment"];
[query whereKey:@"post" matchesQuery:innerQuery];

To retrieve objects whose given field does not contain AVObject that matches a different query, use doesNotMatchQuery instead.

Sometimes you may need to look for related objects from different classes without extra queries. In such situations, you can use includeKey on the same query. The following code retrieves the last 10 comments together with the posts related to them:

AVQuery *query = [AVQuery queryWithClassName:@"Comment"];

// Retrieve the most recent ones
[query orderByDescending:@"createdAt"];

// Only retrieve the last 10
query.limit = 10;

// Include the related post together with each comment
[query includeKey:@"post"];

[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments contains the last 10 comments including the post associated with each
    for (AVObject *comment in comments) {
        // This does not require a network access
        AVObject *post = comment[@"post"];
    }
}];

You can even indicate multi-level associations using dot notations. If you wanted to include the post for each comment as well as the author of the post, you can do:

[query includeKey:@"post.author"];

Feel free to use includeKey as many times as you need for the same query to have multiple fields included. Related objects retrieved in this way also works with AVQuery helpers like getFirstObject.

You can also use dot notations with selectKeys to limit the fields returned from the related objects:

[query selectKeys:@[@"post.author.firstName"]];

Caveats about Relational Queries

The backend of LeanCloud is not built on relational databases, which makes it impossible to join tables while querying. For the relational queries mentioned above, what LeanCloud would do is to first perform an inner query (with 100 as default limit and 1000 as maximum) and then insert the result from this query into the outer query. If the number of records matching the inner query exceeds the limit and the outer query contains other constraints, the amount of the records returned in the end could be zero or less than your expectation since only the records within the limit would be inserted into the outer query.

The following actions can be taken to solve the problem:

• Make sure the number of records in the result of the inner query is no more than 100. If it is between 100 and 1,000, set 1000 as the limit of the inner query.
• Create redundancy for the fields being queried by the inner query on the table for the outer query.
• Repeat the same query with different skip values until all the records are gone through (performance issue could occur if the value of skip gets too big).

Counting Objects

If you just need to count how many objects match a query but do not need to retrieve the actual objects, use countObjectsInBackgroundWithBlock instead of findObjectsInBackgroundWithBlock. For example, to count how many todos have been completed:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query whereKey:@"isComplete" equalTo:@(YES)];
[query countObjectsInBackgroundWithBlock:^(NSInteger count, NSError *error) {
    NSLog(@"%ld todos completed.", count);
}];

Compound Queries

Compound queries can be used if complex query conditions need to be specified. A compound query is a logical combination (OR or AND) of subqueries.

OR-ed Query Constraints

An object will be returned as long as it fulfills any one of the subqueries. The code below constructs a query that looks for all the todos that either have priorities higher than or equal to 3, or are already completed:

AVQuery *priorityQuery = [AVQuery queryWithClassName:@"Todo"];
[priorityQuery whereKey:@"priority" greaterThanOrEqualTo:@3];

AVQuery *isCompleteQuery = [AVQuery queryWithClassName:@"Todo"];
[isCompleteQuery whereKey:@"isComplete" equalTo:@(YES)];

AVQuery *query = [AVQuery orQueryWithSubqueries:[NSArray arrayWithObjects:priorityQuery, isCompleteQuery, nil]];

AND-ed Query Constraints

The effect of using AND-ed query is the same as adding constraints to AVQuery. The code below constructs a query that looks for all the todos that are created between 2016-11-13 and 2016-12-02:

NSDate *(^dateFromString)(NSString *string) = ^(NSString *string) {
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    [dateFormatter setDateFormat:@"yyyy-MM-dd"];
    return [dateFormatter dateFromString:string];
};

AVQuery *startDateQuery = [AVQuery queryWithClassName:@"Todo"];
[startDateQuery whereKey:@"createdAt" greaterThanOrEqualTo:dateFromString(@"2016-11-13")];

AVQuery *endDateQuery = [AVQuery queryWithClassName:@"Todo"];
[endDateQuery whereKey:@"createdAt" lessThan:dateFromString(@"2016-12-03")];

AVQuery *query = [AVQuery andQueryWithSubqueries:[NSArray arrayWithObjects:startDateQuery, endDateQuery, nil]];

While using an AND-ed query by itself doesn't bring anything new comparing to a basic query, combining AND-ed queries with OR-ed queries together allows you to implement complicated query conditions in your program. The code below constructs a query that looks for all the todos created today that either have no location set or have 3 as priority:

NSDate *(^dateFromString)(NSString *string) = ^(NSString *string) {
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    [dateFormatter setDateFormat:@"yyyy-MM-dd"];
    return [dateFormatter dateFromString:string];
};

AVQuery *createdAtQuery = [AVQuery queryWithClassName:@"Todo"];
[createdAtQuery whereKey:@"createdAt" greaterThanOrEqualTo:dateFromString(@"2018-04-30")];
[createdAtQuery whereKey:@"createdAt" lessThan:dateFromString(@"2018-05-01")];

AVQuery *locationQuery = [AVQuery queryWithClassName:@"Todo"];
[locationQuery whereKeyDoesNotExist:@"location"];

AVQuery *priorityQuery = [AVQuery queryWithClassName:@"Todo"];
[priorityQuery whereKey:@"priority" equalTo:@3];

AVQuery *orQuery = [AVQuery orQueryWithSubqueries:[NSArray arrayWithObjects:locationQuery, priorityQuery, nil]];
AVQuery *query = [AVQuery andQueryWithSubqueries:[NSArray arrayWithObjects:createdAtQuery, orQuery, nil]];

Optimizing Performance

There are several factors that could lead to potential performance issues when you conduct a query, especially when more than 100,000 records are returned at a time. We are listing some common ones here so you can design your apps accordingly to avoid them:

• Querying with "not equal to" or "not include" (index will not work)
• Querying on strings with a wildcard at the beginning of the pattern (index will not work)
• Using count with conditions (all the entries will be gone through)
• Using skip for a great number of entries (all the entries that need to be skipped will be gone through)
• Sorting without index (querying and sorting cannot share a composite index unless the conditions used on them are both covered by the same one)
• Querying without index (the conditions used on the query cannot share a composite index unless all of them are covered by the same one; additional time will be consumed if excessive data falls under the uncovered conditions)

LiveQuery

LiveQuery is, as its name implies, derived from AVQuery but has enhanced capability. It allows you to automatically synchronize data changes from one client to other clients without writing complex code, making it suitable for apps that need real-time data.

Suppose you are building an app that allows multiple users to edit the same file at the same time. AVQuery would not be an ideal tool since it is based on a pull model and you cannot know when to query from the cloud to get the updates.

To solve this problem, we introduced LiveQuery. This tool allows you to subscribe to the AVQuerys you are interested in. Once subscribed, the cloud will notify clients by generating event messages whenever AVObjects that match the AVQuery are created or updated, in real-time.

Behind the scene, we use WebSocket connections to have clients and the cloud communicate with each other and maintain the subscription status of clients. In most cases, it isn't necessary to deal with the WebSocket connections directly, so we developed a simple API to help you focus on your business logic rather than technical implementations.

Initializing LiveQuery

To use LiveQuery in your app, go to your app's Dashboard > LeanStorage > Settings and check the Enable LiveQuery option under the Other section, then add the following pod into the Podfile under the project's root directory:

pod 'AVOSCloudLiveQuery'

See Installing SDK for more details.

Creating a Subscription

To make a query live, create a normal AVQuery object, put conditions on it if there are, and then subscribe to it:

AVQuery *query = [AVQuery queryWithClassName:@"Employee"];
self.liveQuery = [[AVLiveQuery alloc] initWithQuery:query];
self.liveQuery.delegate = self;
[self.liveQuery subscribeWithCallback:^(BOOL succeeded, NSError * _Nonnull error) {
    // Query becomes live after getting a subscription
}];

Now you will be able to receive updates related to AVObject. If an Employee object is created by another client with Kelly as firstName, the following code can get the new Employee for you:

AVQuery *query = [AVQuery queryWithClassName:@"Employee"];
self.liveQuery = [[AVLiveQuery alloc] initWithQuery:query];
self.liveQuery.delegate = self;
[self.liveQuery subscribeWithCallback:^(BOOL succeeded, NSError * _Nonnull error) {
    // Query becomes live after getting a subscription
}];
- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidCreate:(id)object {
    if (liveQuery == self.liveQuery) {
        NSLog(@"%@", object[@"firstName"]); // Kelly
    }
}

If someone updates this Employee by changing its team to Finance, the following code can get the updated version for you:

- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidUpdate:(id)updatedEmployee updatedKeys:(NSArray<NSString *> *)updatedKeys {
    NSLog(@"%@", updatedEmployee[@"team"]); // Finance
}

Event Handling

The following types of data changes can be monitored once subscription is set up:

• create
• update
• enter
• leave
• delete
• login

create Event

A create event will be triggered when a new AVObject is created and it fulfills the AVQuery you subscribed. The object is the new AVObject being created:

- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidCreate:(id)object {
    if (liveQuery == self.liveQuery) {
        NSLog(@"Object created.");
    }
}

update Event

An update event will be triggered when an existing AVObject fulfilling the AVQuery you subscribed is updated. The object is the AVObject being updated:

- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidUpdate:(id)object updatedKeys:(NSArray<NSString *> *)updatedKeys {
    if (liveQuery == self.liveQuery) {
        NSLog(@"Object updated.");
    }
}

enter Event

An enter event will be triggered when an existing AVObject's old value does not fulfill the AVQuery you subscribed but its new value does. The object is the AVObject entering the AVQuery and its content is the latest value of it:

- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidEnter:(id)object updatedKeys:(nonnull NSArray<NSString *> *)updatedKeys {
    if (liveQuery == self.liveQuery) {
        NSLog(@"Object entered.");
    }
}

leave Event

A leave event will be triggered when an existing AVObject's old value fulfills the AVQuery you subscribed but its new value does not. The object is the AVObject leaving the AVQuery and its content is the latest value of it:

- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidLeave:(id)object updatedKeys:(nonnull NSArray<NSString *> *)updatedKeys {
    if (liveQuery == self.liveQuery) {
        NSLog(@"Object left.");
    }
}

delete Event

A delete event will be triggered when an existing AVObject fulfilling the AVQuery you subscribed is deleted. The object is the objectId of the AVObject being deleted:

- (void)liveQuery:(AVLiveQuery *)liveQuery objectDidDelete:(id)object {
    if (liveQuery == self.liveQuery) {
        NSLog(@"Object deleted.");
    }
}

login Event

A login event will be triggered when a user successfully logs in to your app. The user is the AVUser logged in:

- (void)liveQuery:(AVLiveQuery *)liveQuery userDidLogin:(AVUser *)user {
    if (liveQuery == self.liveQuery) {
        NSLog(@"User logged in.");
    }
}

Unsubscribing

You can cancel a subscription to stop receiving events regarding AVQuery. After that, you won't get any events from the subscription.

[liveQuery unsubscribeWithCallback:^(BOOL succeeded, NSError * _Nonnull error) {
    if (succeeded) {
        // Successfully unsubscribed
    } else {
        // Error handling
    }
}];

Losing Connections

There are different scenarios regarding losing connections:

1. The connection to the Internet is lost unexpectedly.
2. The user performs certain operations outside of the app, like switching the app to the background, turning off the phone, or turning on the flight mode.

For the scenarios above, you don't need to do any extra work. As long as the user switches back to the app, the SDK will automatically re-establish the connection.

There is another scenario when the user completely kills the app or closes the web page. In this case, the SDK cannot automatically re-establish the connection. You will have to create subscriptions again by yourself.

Caveats about LiveQuery

Given the real-time feature of LiveQuery, developers may find it tempting to use it for instant messaging. As LiveQuery is neither designed nor optimized for completing such tasks, we discourage such use of this tool, let alone there will be additional cost for saving message history and rising challenges of code maintenance. We recommend using our real-time messaging solution for this scenario.

Files

AVFile allows you to store application files in the cloud that would otherwise be too large or cumbersome to fit into a regular AVObject. The most common use case is storing images, but you can also use it for documents, videos, music, and any other binary data.

Creating Files

You can create a file from a string:

NSData *data = [@"LeanCloud" dataUsingEncoding:NSUTF8StringEncoding];
// resume.txt is the file name
AVFile *file = [AVFile fileWithData:data name:@"resume.txt"];

You can also create a file from a URL:

AVFile *file = [AVFile fileWithRemoteURL:[NSURL URLWithString:@"https://leancloud.cn/assets/imgs/press/Logo%20-%20Blue%20Padding.a60eb2fa.png"]];

But the most common method for creating files is to upload them from local paths:

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
NSString *documentsDirectory = [paths objectAtIndex:0];
NSString *imagePath = [documentsDirectory stringByAppendingPathComponent:@"avatar.jpg"];
NSError *error;
AVFile *file = [AVFile fileWithLocalPath:imagePath error:&error];

The file we uploaded here is named avatar.jpg. There are a couple of things to note here:

• Each file uploaded will get its unique objectId, so it is allowed for multiple files to share the same name.
• A correct extension needs to be assigned to each file which the cloud will use to infer the type of a file. For example, if you are storing a PNG image with AVFile, use .png as its extension.
• If the file doesn't have an extension and the content type is not specified, LeanCloud defaults the file's type to be application/octet-stream.

Saving Files

By saving a file, you store it into the cloud and get a permanent URL pointing to it:

[file uploadWithCompletionHandler:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        NSLog(@"File uploaded. objectId: %@", file.objectId);
    } else {
        // The file either could not be read or could not be saved to LeanCloud
    }
}];

You can associate a file with AVObject after it is saved:

AVObject *todo = [AVObject objectWithClassName:@"Todo"];
[todo setObject:@"Get Cakes" forKey:@"title"];
// attachments is an Array field
[todo addObject:file forKey:@"attachments"];
[todo saveInBackground];

On a related note, if the files are referenced in an array field of AVObject and you want to get them within the same query for AVObject, you need to use the includeKey method with AVQuery. For example, if you are retrieving all the todos with the same title Get Cakes and you want to retrieve their related attachments at the same time:

// Get all todos with the same title and contain attachments
AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
[query whereKey:@"title" equalTo:@"Get Cakes"];
[query whereKeyExists:@"attachments"];

// Include attachments with each todo
[query includeKey:@"attachments"];

[query findObjectsInBackgroundWithBlock:^(NSArray * _Nullable todos, NSError * _Nullable error) {
    for (AVObject *todo in todos) {
        // Get attachments array for each todo
        // 
    }
}];

Upload Progress

You can monitor the progress of uploading and display that to the user:

[file uploadWithProgress:^(NSInteger percent) {
    // percent is an integer between 0 and 100, indicating uploading progress
} completionHandler:^(BOOL succeeded, NSError *error) {
    // Things to do after saving
}];

File Metadata

When uploading a file, you can attach additional properties to it with metaData. A file's metaData cannot be updated once the file is stored to the cloud.

// Set metadata
[file.metaData setObject:@"LeanCloud" forKey:@"author"];
[file uploadWithCompletionHandler:^(BOOL succeeded, NSError *error) {
    // Get all metadata
    NSDictionary *metadata = file.metaData;
    // Get author
    NSString *author = metadata[@"author"];
    // Get file name
    NSString *fileName = file.name;
    // Get size (not available for files created from base64-encoded strings or URLs)
    NSUInteger *size = file.size;
}];

Deleting Files

The code below deletes a file from the cloud:

AVFile *file = [AVFile getFileWithObjectId:@"552e0a27e4b0643b709e891e"];
[file deleteInBackground];

Enabling HTTPS

If you demand that the files in the cloud should be accessed through HTTPS, check on Enable HTTPS domain in Dashboard > LeanStorage > Settings > Custom domain for files. There is no free quota on using HTTPS for files and you will see the pricing once the function is enabled.

After enabling HTTPS, the URLs of the files previously stored in the _File table will be converted to HTTPS. If you disable the function, the URLs being converted will not change back.

LeanMessage stores files sent through messages with AVFile and the URLs of the files will be included in the messages. After HTTPS is enabled, the URLs of the files sent in the past messages will not be automatically converted like what happens in _File.

HTTP Support for iOS 9 and Up

Starting iOS 9, Apple requires HTTPS connections for iOS apps and denies HTTP connections by default. All LeanCloud APIs support HTTPS except for the getData method of AVFile.

If your app still needs to make HTTP requests, such as when accessing files in LeanMessage that still reference to insecure domains, you should add those insecure domains to your project's Info.plist:

Right-click on Info.plist, choose Opened As > Source Code, append the following text to the node plist > dict:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSExceptionDomains</key>
  <dict>
    <key>amazonaws.com</key>
    <dict>
      <key>NSIncludesSubdomains</key>
      <true/>
      <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
      <true/>
    </dict>
  </dict>
</dict>

You may also allow all HTTP traffics if you need. See iOS9AdaptationTips for more information.

Setting up Custom Domain

LeanCloud offers a shared domain for all the apps to access the files stored in the cloud. However, due to the Cyber Security Law of the countries where we offer our services, the shared domain might not be available all the time. We highly recommend that you set up your custom domains for accessing files so that your apps will not be affected when the shared domain becomes unavailable. You can set up custom domains at Dashboard > LeanStorage > Settings > Custom domain for files.

The setup of custom domains is irreversible. You cannot unbind domains, but you can change the domains at any time.

When binding domains, you can choose if you want to enable HTTPS:

• If you don't enable HTTPS, clients can only access files via HTTP.
• If you enable HTTPS, clients can access files via both HTTPS and HTTP.

CDN Support

You can set up your own CDN to improve the speed your users access the files stored on LeanCloud. Take Amazon CloudFront CDN as an example:

1. Read Getting Started with CloudFront.
2. Create an Amazon AWS account, and choose a CloudFront subscription plan that suits your business.
3. LeanCloud has got S3's read permission properly configured, so you can skip Step 2: Upload your content to Amazon S3 and grant object permissions in the guide and proceed with other steps.
4. Take the domain name from the URL of your AVFile and fill it into CloudFront's Origin Domain Name. Leave the other settings with defaults.

GeoPoints

LeanCloud allows you to associate real-world latitude and longitude coordinates with an object by adding AVGeoPoint to the AVObject. By doing so, queries on the proximity of an object to a given point can be performed, allowing you to easily implement functions like looking for users or places nearby.

To associate a point with an object, you need to create the point first. The code below creates AVGeoPoint with 39.9 as latitude and 116.4 as longitude:

AVGeoPoint *point = [AVGeoPoint geoPointWithLatitude:39.9 longitude:116.4];

Now you can store the point in an object as a regular field:

[todo setObject:point forKey:@"location"];

Geo Queries

With a number of existing objects with spatial coordinates, you can find out which of them are closest to a given point, or are contained within a particular area. This can be done by adding another restriction to AVQuery using nearGeoPoint. The code below returns a list of Todo objects with location closest to a given point:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
AVGeoPoint *point = [AVGeoPoint geoPointWithLatitude:39.9 longitude:116.4];
[query whereKey:@"location" nearGeoPoint:point];

// Limit to 10 results
query.limit = 10;
[query findObjectsInBackgroundWithBlock:^(NSArray *todos, NSError *error) {
    // todos is an array of Todo objects satisfying conditions
}];

To have the results limited within a certain distance, check out withinKilometers, withinMiles, and withinRadians in our API docs.

You can also query for the set of objects that are contained within a rectangular bounding box with withinGeoBoxFromSouthwest and toNortheast:

AVQuery *query = [AVQuery queryWithClassName:@"Todo"];
AVGeoPoint *southwest = [AVGeoPoint geoPointWithLatitude:30 longitude:115];
AVGeoPoint *northeast = [AVGeoPoint geoPointWithLatitude:40 longitude:118];
[query whereKey:@"location" withinGeoBoxFromSouthwest:southwest toNortheast:northeast];

Caveats about GeoPoints

There are a couple of things to keep in mind:

• Each AVObject may only have one field containing AVGeoPoint object.
• Points should not exceed the extreme ends of the ranges. Latitude should be between -90.0 and 90.0. Longitude should be between -180.0 and 180.0. Attempting to set latitude or longitude out of bounds will cause an error.

Users

At the core of many apps, there is a notion of user accounts that allows users to access their information in a secure manner. We provide a specialized user class called AVUser which automatically handles much of the functionality required for user account management in your app.

AVUser is a subclass of AVObject. Therefore, all the methods that work for AVObject also work for AVUser. The only difference is that AVUser has some additional features specific to user accounts. Each app has a dedicated _User class for storing AVUser.

User Properties

AVUser offers the following fields that AVObject does not have:

• username: The username of the user.
• password: The password of the user.
• email: The email address of the user.
• emailVerfied: Whether the user has verified the email address with LeanCloud or not.
• mobilePhoneNumber: The mobile phone number of the user.
• mobilePhoneVerfied: Whether the user has verified the mobile phone number with LeanCloud or not.

We'll go through each of these in detail as we run through the various use cases for users.

Signing up

When a user first opens your app, you may want them to sign up for an account. The following code shows a typical sign-up process with username and password:

// Create an instance
AVUser *user = [AVUser user];

// Same as [user setObject:@"Tom" forKey:@"username"]
user.username = @"Tom";
user.password = @"cat!@#123";

// Optional
user.email = @"tom@leancloud.rocks";
user.phoneNumber = @"+19490008888";

// Other fields can be set in the same way as AVObject
[user setObject:@"secret" forKey:@"gender"];

[user signUpInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        // Sign-up completed
        NSLog(@"User created. objectId: %@", user.objectId);
    } else {
        // Sign-up failed (often because the username is already taken)
    }
}];

If the code returns the error 202, it means that a user with the same username already exists in _User table and the client should prompt the user to try a different username. It is also required that each email or mobilePhoneNumber appears only once in the corresponding column, otherwise error 203 or 214 will occur. You may ask a user to sign up with an email address and make the username to be the same as the email. By doing so, the user can directly reset their password with email.

Signing up with Phones

For a mobile app, it's also common to ask users to sign up with their phone numbers instead of usernames and passwords. There are two basic steps in it. First, ask the user to enter a phone number that can receive text messages. When the user clicks on the "Get Verification Code" button, call the following method to have a 6-digit verification code sent to the phone number the user just entered:

[AVOSCloud requestSmsCodeWithPhoneNumber:@"+19490008888"];

After the verification code is entered by the user, call the following method to finish signing up:

[AVUser signUpOrLoginWithMobilePhoneNumberInBackground:@"+19490008888" smsCode:@"123456" block:^(AVUser *user, NSError *error) {
    if (user != nil) {
        // Sign-up completed
        NSLog(@"User created. objectId: %@", user.objectId);
    } else {
        // Verification code is incorrect
    }
}];

Phone Number Format

A phone number that AVUser accepts should have a leading plus sign (+) immediately followed by the country code and the phone number without any dashes, spaces, or other non-numeric characters. For instance, +8618200008888 is a valid China number (86 is the country code) and +19490008888 is a valid US or Canada number (1 is the country code).

For a list of countries and regions that LeanCloud can reach out through SMS, please refer to the Pricing section of the SMS guide.

Logging in

The code below logs a user in with username and password:

[AVUser logInWithUsernameInBackground:@"Tom" password:@"cat!@#123" block:^(AVUser *user, NSError *error) {
    if (user != nil) {
        // Logged in successfully
    } else {
        // Failed to log in (the password may be incorrect)
    }
}];

Logging in with Emails

The code below logs a user in with email and password:

[AVUser loginWithEmail:@"tom@leancloud.rocks" password:@"cat!@#123" block:^(AVUser *user, NSError *error) {
    if (user != nil) {
        // Logged in successfully
    } else {
        // Failed to log in (the password may be incorrect)
    }
}];

Logging in with Phones

If you are allowing users to sign up with their phone numbers, you can also let them log in with either a password or a verification code sent via text message. The code below logs a user in with phone number and password:

[AVUser logInWithMobilePhoneNumberInBackground:@"+19490008888" password:@"cat!@#123" block:^(AVUser *user, NSError *error) {
    if (user != nil) {
        // Logged in successfully
    } else {
        // Failed to log in (the password may be incorrect)
    }
}];

You may also let a user in with a verification code sent to their phone, which is useful when the user forgets the password and does not want to reset it at the moment. Similar to the steps of signing a user up with phone numbers, ask the user to enter the phone number associated with the account, and call the following method once the user clicks on the "Get Verification Code" button:

[AVUser requestLoginSmsCode:@"+19490008888"];

After the verification code is entered by the user, call the following method to finish logging in:

[AVUser logInWithMobilePhoneNumberInBackground:@"+19490008888" smsCode:@"123456" block:^(AVUser *user, NSError *error) {
    if (user != nil) {
        // Logged in successfully
    } else {
        // Verification code is incorrect
    }
}];

Sandbox Phone Number

During the development of your application, you may need to test the sign-up or log-in related API intensively with your phone. As there are, however, limits to how quickly messages can be sent into the carrier networks, your testing pace can be greatly affected.

To work around it, you can set up a sandbox phone number in Dashboard > Messaging > SMS > Settings. LeanCloud will issue a fixed verification code to go with that sandbox phone number. Whenever LeanCloud detects such combination of data, the user will be let right in authenticated without any connections to the carrier networks being made.

On a related note, a sandbox phone number also comes in handy for iOS apps that allow users to log in with SMS code. This is because Apple may ask developers to provide a fixed combination of phone number and verification code for them to review the app as a normal user. Failure to do so may result in their app being rejected by App Store.

For more details regarding limitations of sending and receiving SMS messages, see SMS Guide.

Single Device Sign-on

In some scenarios you may want to restrict a user's account to be logged on by no more than one device at a time, that is, when a user logs in to the app on a new device, all the previous sessions on other devices will become invalid. Here's the instruction about how you can implement this feature with LeanCloud:

1. Create a new class that keeps track of each user's credentials and their device information.
2. Each time when a user logs in on a device, update the device information of this user to be the current device.
3. When the app running on another device is opened, check if the device matches the one stored in the cloud. If it does not, log the user out.

User Account Lockout

If the wrong password or verification code is entered for an account for more than 6 times within 15 minutes, the account will be disabled temporarily and the error { "code": 1, "error": "You have exceeded the maximum number of login attempts, please try again later, or consider resetting your password." } will be returned.

The account will be automatically recovered 15 minutes after the last attempt and the process cannot be expedited through SDK or REST API. While the account is disabled, the user cannot be logged in even though the correct credentials are provided. The restriction applies to both client-side SDKs and LeanEngine.

Verifying Emails

You can request that your users have their email addresses verified before they can log in or access certain functions in your app. This makes it harder for spam users to abuse your app. By default, each user has an emailVerified field which becomes false when the user first signs up or has their email address changed. In your app's Dashboard > LeanStorage > Settings, you can enable Send verification emails when users register or change email addresses from clients so that when a user signs up or changes their email address, an email containing a verification link will be sent out automatically. You can find the option to prevent users with unverified email addresses from logging in on the same page.

If a user forgets to click on the link and needs to have their account verified later, the following code can be used to send a new email:

[AVUser requestEmailVerify:@"tom@leancloud.rocks"];

The emailVerified will become true after the link is clicked on. This field can never be true when the email field is empty.

Verifying Phone Numbers

Similar to Verifying Emails, you can also request that your users have their phone numbers verified before they can log in or access certain functions in your app. By default, each user has a mobilePhoneVerified field which becomes false when the user first signs up or has their phone number changed. In your app's Dashboard > LeanStorage > Settings, you can enable Send verification SMS when users register or change phone numbers from clients so that when a user signs up or changes their phone number, a text message containing a verification code will be sent out automatically. You can find the option to prevent users with unverified phone numbers from logging in on the same page.

You can also initiate a verification request at anytime with the following code:

[AVUser requestMobilePhoneVerify:@"+19490008888"];

After the verification code is entered by the user, call the following method and the user's mobilePhoneVerified will become true:

[AVUser verifyMobilePhone:@"123456" block:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        // mobilePhoneVerified is set to true
    } else {
        // Verification code is incorrect
    }
}];

Current User

After a user is logged in, LeanCloud SDK automatically stores the session information of this user in the client so that the user does not need to log in each time they open the client. The following code checks if there is a user logged in:

AVUser *currentUser = [AVUser currentUser];
if (currentUser != nil) {
    // Redirect to the home page
} else {
    // Show the sign-up or log-in page
}

The session information of a user will remain in the client until the user is logged out:

[AVUser logOut];

// currentUser becomes nil
AVUser *currentUser = [AVUser currentUser];

Setting The Current User

A session token will be returned to the client after a user is logged in. It will be cached by our SDK and will be used for authenticating requests made by the same AVUser in the future. The session token will be included in the header of each HTTP request made from the client, which helps the cloud identify the AVUser sending the request.

Below are the situations when you may need to log a user in with session token:

• A session token is already cached on the client which can be used to automatically log the user in (you can use to get the session token of the current user).
• A WebView within the app needs to know the current user.
• The user is logged in on the server side using your own authentication routines and the server is able to provide the session token to the client.

The code below logs a user in with session token (the session token will be validated before proceeding):

[AVUser becomeWithSessionTokenInBackground:@"anmlwi96s381m6ca7o7266pzf" block:^(AVUser * _Nullable user, NSError * _Nullable error) {
    if (user != nil) {
        // Logged in successfully
    } else {
        // Session token is invalid
    }
}];

The code below checks if a session token is valid:

AVUser *currentUser = [AVUser currentUser];
NSString *token = currentUser.sessionToken;
[currentUser isAuthenticatedWithSessionToken:token callback:^(BOOL succeeded, NSError * _Nullable error) {
    if (succeeded) {
        // The session token is valid
    } else {
        // The session token is invalid
    }
}];

Resetting Passwords

It's quite common for the users of an app to forget their passwords. LeanCloud provides a number of ways for them to reset their passwords.

Here is the flow of resetting password with email:

1. The user enters the email address used for the account.
2. LeanCloud sends an email to the address including a link for resetting password.
3. After the user clicks on the link, a new page will pop up, asking for a new password.
4. The password will be reset after the user enters a new password.

To start with, ask the user to enter the email used for the account, and call the function below:

[AVUser requestPasswordResetForEmailInBackground:@"tom@leancloud.rocks"];

The code above will check if there is a user in the _User table that has the email to be the same as the one provided, and will send them a password reset email if so. As mentioned previously, you can make the username of each user to be the same as their email, or collect the email separately and store it in the email field.

Alternatively, you can ask for the mobile phone number instead of the email to reset their password:

1. The user enters the mobile phone number used for the account.
2. LeanCloud sends a short message to the number including a verification code.
3. The user types in the verification code and a new password.

The code below sends a verification code to a number:

[AVUser requestPasswordResetWithPhoneNumber:@"+19490008888"];

The code above will check if there is a user in the _User table that has the mobilePhoneNumber to be the same as the one provided, and will send them a verification code if so.

The code below resets the password of a user after they enter the verification code and a new password:

[AVUser resetPasswordWithSmsCode:@"123456" newPassword:@"cat!@#123" block:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        // Password is updated
    } else {
        // Verification code is incorrect
    }
}];

Queries on Users

To query for users, you can simple create a new AVQuery for _User:

AVQuery *userQuery = [AVUser query];

For security reasons, the _User table of each new app has its find permission disabled by default. Each user can only access their own data in _User table and cannot access that of others. If you need to allow each user to view other users' data, we recommend that you create a new table to store such data and enable the find permission of this table. You may also encapsulate queries on users within LeanEngine and avoid opening up find permissions of _User tables.

See Security of User Objects for other restrictions applied to the _User table, and Data and Security for more information regarding class-level permission settings.

Associations

Associations involving AVUser works in the same way as basic AVObject. The code below saves a new book for an author and retrieves all the books written by that author:

AVObject *book = [AVObject objectWithClassName:@"Book"];
AVUser *author = [AVUser currentUser];
[book setObject:@"My Fifth Book" forKey:@"title"];
[book setObject:author forKey:@"author"];
[book saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
    // Find all the books by the same author
    AVQuery *query = [AVQuery queryWithClassName:@"Book"];
    [query whereKey:@"author" equalTo:author];
    [query findObjectsInBackgroundWithBlock:^(NSArray *books, NSError *error) {
        // books is an array of Book objects by the same author
    }];
}];

Security of User Objects

The AVUser class is secured by default. You are not able to invoke any save- or delete-related methods unless the AVUser was obtained using an authenticated method like logInWithUsername or signUpInBackground. This ensures that each user can only update their own data.

The reason behind is that most data stored in AVUser can be very personal and sensitive, such as mobile phone number, social network account ID, etc. Even the app's owner should avoid tampering with these data for the sake of user's privacy.

The code below illustrates this security policy:

[AVUser logInWithUsernameInBackground:@"Tom" password:@"cat!@#123" block:^(AVUser *user, NSError *error) {
    if (user != nil) {
        // Attempt to change username
        [user setObject:@"Jerry" forKey:@"username")];
        // Password is hashed and an empty string will be returned
        NSString *password = user[@"password"];
        // Save changes
        [user saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
            if (succeeded) {
                // This will work since the user is authenticated

                // Get the user with a non-authenticated method
                AVQuery *query = [AVQuery queryWithClassName:@"_User"]; 
                [query getObjectInBackgroundWithId:user.objectId block:^(AVObject *unauthenticatedUser, NSError *error) {
                    [unauthenticatedUser setObject:@"Toodle" forKey:@"username"];
                    [unauthenticatedUser saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
                        if (succeeded) {
                            // This will not succeed since the user is unauthenticated
                        } else {
                            // Failure is expected
                        }
                    }];
                }];
            } else {
                // Error handling
            }
        }];
    } else {
        // Error handling
    }
}];

The AVUser obtained from [AVUser currentUser] will always be authenticated.

To check if AVUser is authenticated, you can invoke the isAuthenticatedWithSessionToken method. You do not need to check if AVUser is authenticated if it is obtained via an authenticated method.

As a reminder, the user's password can be set when signing up but cannot be modified and saved to the cloud afterwards unless the user requests it to be reset. It will not be cached on the client and will show as null when being retrieved from the cloud after the user is logged in.

Security of Other Objects

For each given object, you can specify which users are allowed to read it and which are allowed to modify it. To support this type of security, each object has an access control list, implemented by the AVACL class. More details can be found in ACL Guide.

Linking Users

LeanCloud allows you to link your users with services like GitHub, Twitter, and Facebook (commonly known as social networking services, or SNS), allowing your users to sign up or log into your application using their existing identities. For example, to sign up or log in with a user's GitHub account, your code will look like this:

LeanCloud then verifies that the provided authData is valid and checks if a user is already associated with it. If so, it returns the status code 200 OK along with the details (including a sessionToken for the user).

If the authData is not linked to any account, you will instead receive the status code 201 Created, indicating that a new user has been created. The body of the response contains objectId, createdAt, sessionToken, and an automatically-generated unique username. For example:

{
  "username":     "k9mjnl7zq9mjbc7expspsxlls",
  "objectId":     "5b029266fb4ffe005d6c7c2e",
  "createdAt":    "2018-05-21T09:33:26.406Z",
  "updatedAt":    "2018-05-21T09:33:26.575Z",
  "sessionToken": "…",
  // By default authData won't show up here
  // See explanations below
  "authData": {
    // …
  }
  // …
}

By default, authData cannot be returned to the client unless the record is owned by the current user. To change this behavior, you can go to your app's Dashboard > LeanStorage > Data > _User, click on the arrow icon on the authData column header, click on Edit, and check off the Only owners can read and write option so that anyone can have access to it.

To ensure that each AVUser is linked to each service account only once, a unique index needs to be created for the authData.<SERVICE_NAME>.uid key in the _User class.

Authentication Data

authData is a JSON object with the names of services as keys and the details as values. You are responsible for completing the authentication flow (usually through OAuth 1.0 or 2.0) to obtain the details from the service provider which is required for linking.

A user who has GitHub linked may have the following object as authData:

{
  "github": {
    "uid":           "…",
    "access_token":  "…",
    "expires_in":    7200,
    "refresh_token": "…",
    "scope":         "…"
  }
}

LeanCloud automatically validates the access tokens for certain services to prevent data forge attack. When the validation fails, LeanCloud will respond with invalid authData error and the linking will not be established. For services that are not recognized by LeanCloud, you are responsible for validating access tokens by yourself. You can turn off the Validate access tokens when logging in with third-party accounts option in your app's Dashboard > LeanStorage > Settings if you prefer not to have LeanCloud validate access tokens for you.

Unlinking

You can unlink a service by setting the authData for the service to null. The code below unlinks a user's GitHub account:

Anonymous Users

With the support of anonymous users, you can have your users try the application without signing up or logging in. The code below creates an anonymous user:

[AVUser loginAnonymouslyWithCallback:^(AVUser *user, NSError *error) {
    // user is the new anonymous user
}];

You can add new properties or fields to an anonymous user just like with a normal user, such as username, password, email, etc. You can also convert an anonymous user to a normal user by going through the same sign-up process as you do with a normal user. An anonymous user can:

• Sign up with username and password.
• Link to a third-party service or platform, such as GitHub.

The code below sets a username and password for an anonymous user:

// currentUser is the anonymous user
AVUser *currentUser = [AVUser currentUser];

user.username = @"Tom";
user.password = @"cat!@#123";

[user signUpInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
    if (succeeded) {
        // currentUser has become a normal user
    } else {
        // Sign-up failed (often because the username is already taken)
    }
}];

The code below checks if the current user is anonymous:

AVUser *currentUser = [AVUser currentUser];
if (currentUser.isAnonymous) {
    // currentUser is anonymous
} else {
    // currentUser is not anonymous
}

If an anonymous user is not converted to a normal user before they log out, they will not be able to log in to the same account later and the data stored in that account cannot be retrieved anymore.

Roles

As your app grows in scope and user-base, you may find yourself needing more coarse-grained control over access to pieces of your data than user-linked ACLs can provide. To address this requirement, LeanCloud supports a form of role-based access control. Check the detailed ACL Guide to learn how to set it up for your objects.

In-App Searching

In-App Searching offers a better way to search through the information contained within your apps. It's built with search engine capabilities that you can easily tap into your app. Effective and useful searching functionality in your app is crucial for helping users find what they need. For more details, see In-App Searching Guide.

In-App Socializing

In-app socializing offers features like following, timeline, status update, interaction, messaging, etc. For more details, see In-App Socializing Guide.