> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quickblox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Users
> Learn how to manage your users with QuickBlox.
Visit [Key Concepts](/docs/key-concepts) page to learn the most important QuickBlox concepts.
## Before you begin
1. Register a [QuickBlox account](https://admin.quickblox.com/signin). This is a matter of a few minutes and you will be able to use this account to build your apps.
2. Configure QuickBlox SDK for your app. Check out [Setup](/sdks/ios-setup) page for more details.
3. Create a user session to be able to use QuickBlox functionality. See [Authentication](/sdks/ios-authentication) page to learn how to do it.
## Create user
It's recommended to manage user creation at your backend for production. To learn more you can refer to [QuickBlox API documentation](https://docs.quickblox.com/reference/create-user).
For POCs/MVPs or during development you may want to create users on the fly, you can use `signUp()` method.
Create a user using the code snippet below. Only login (or email) and password are required. Other fields are optional.
```Swift theme={null}
let user = QBUUser()
user.login = "myLogin"
user.fullName = "myFullName"
user.password = "myPassword"
QBRequest.signUp(user, successBlock: { (response, user) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
QBUUser *user = [[QBUUser alloc] init];
user.login = @"myLogin";
user.fullName = @"myFullName";
user.password = @"myPassword";
[QBRequest signUp:user successBlock:^(QBResponse * _Nonnull response, QBUUser * _Nonnull user) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
**Security & Privacy**
It's recommended to [disable permission](/docs/application#set-session-permissions) to create users with application session on **production apps** once user creation is implemented on your backend.
Email, full name, facebookId and phone number are PII, [configure session permissions](/docs/application#set-session-permissions) according to your privacy requirements.
## Retrieve users
Get a list of users using the `users(withExtendedRequest:page:)` method. The code snippet below shows how to get a list of users created between the two given dates and sorted in descending order.
```Swift theme={null}
let field = "created_at"
let typeField = "date"
let sortDesc = "desc"
let sortAsc = "asc"
let paramSort = "order"
let paramFilter = "filter[]"
let searchOperator = "between"
let searchValue = "2021-01-01, 2021-05-06"
var extendedRequest: [String: String] = [:]
extendedRequest[paramSort] = sortDesc + " " + typeField + " " + field
extendedRequest[paramFilter] = typeField + " " + field + " " + searchOperator + " " + searchValue
let page = QBGeneralResponsePage(currentPage: 1, perPage: 100)
QBRequest.users(withExtendedRequest: extendedRequest, page: page, successBlock: { (response, page, users) in
}, errorBlock: { response in
})
```
```Objective-C theme={null}
NSString *field = @"created_at";
NSString *typeField = @"date";
NSString *sortDesc = @"desc";
NSString *sortAsc = @"asc";
NSString *paramSort = @"order";
NSString *paramFilter = @"filter[]";
NSString *searchOperator = @"between";
NSString *searchValue = @"2021-01-01, 2021-05-06";
NSMutableDictionary *extendedRequest = [NSMutableDictionary dictionary];
extendedRequest[paramSort] = [NSString stringWithFormat:@"%@ %@ %@", sortDesc, typeField, field];
extendedRequest[paramFilter] = [NSString stringWithFormat:@"%@ %@ %@ %@", typeField, field, searchOperator, searchValue];
QBGeneralResponsePage *page = [QBGeneralResponsePage responsePageWithCurrentPage:1 perPage:10];
[QBRequest usersWithExtendedRequest:extendedRequest.copy page:page successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
| Argument | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| extendedRequest | yes | A dictionary that stores keys and values of the String type. |
| page | no | If you want to get a paginated list of users from the server, you can set the following fields of the page:- currentpage is a number of pages with results to be returned.- perPage is a number of records to return in one page. |
If you want to retrieve only users updated after some specific date time, you can use operators. This is useful if you cache users somehow and do not want to obtain the whole list of users on every app start. Thus, you can use [search](/sdks/ios-users#search-operators) and [sort](/sdks/ios-users#sort-operators) operators to list users on the page so that it is easier to see specific users.
### Search operators
You can use search operators to get more specific search results. The request below will return a list of users created between the two given dates.
```Swift theme={null}
let field = "created_at"
let typeField = "date"
let paramFilter = "filter[]"
let searchOperator = "between"
let searchValue = "2021-01-01, 2021-05-06"
var extendedRequest: [String: String] = [:]
extendedRequest[paramFilter] = typeField + " " + field + " " + searchOperator + " " + searchValue
let page = QBGeneralResponsePage(currentPage: 1, perPage: 100)
QBRequest.users(withExtendedRequest: extendedRequest, page: page, successBlock: { (response, page, users) in
}, errorBlock: { response in
})
```
```Objective-C theme={null}
NSString *field = @"created_at";
NSString *typeField = @"date";
NSString *paramFilter = @"filter[]";
NSString *searchOperator = @"between";
NSString *searchValue = @"2021-01-01, 2021-05-06";
NSMutableDictionary *extendedRequest = [NSMutableDictionary dictionary];
extendedRequest[paramFilter] = [NSString stringWithFormat:@"%@ %@ %@ %@", typeField, field, searchOperator, searchValue];
QBGeneralResponsePage *page = [QBGeneralResponsePage responsePageWithCurrentPage:1 perPage:10];
[QBRequest usersWithExtendedRequest:extendedRequest.copy page:page successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
Here are the search operators that you can use to search for the exact data that you need.
| Search operators | Applicable to types | Applicable to fields | Description |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| lt | number, string, date | id, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Less Than** operator. |
| gt | number, string, date | id, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Greater Than** operator. |
| gte | number, string, date | id, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Greater Than** or **Equal** to operator. |
| le | number, string, date | id, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Less or Equal to** operator |
| eq | number, string, date | id, full\_name, email, login, phone, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Equal** to operator. |
| ne | number, string, date | id, full\_name, email, login, phone, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Not Equal** to operator. |
| between | number, string, date | id, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **Contained between values** operator. |
| in | number, string, date | id, full\_name, email, login, phone, created\_at, updated\_at, last\_request\_at, external\_user\_id, facebook\_id | **IN** array operator. |
### Sort operators
You can use sort operators to order the search results. The request below will return a list of users sorted in descending order by the `created_at` field.
```Swift theme={null}
let field = "created_at"
let typeField = "date"
let sortDesc = "desc"
let sortAsc = "asc"
let paramSort = "order"
var extendedRequest: [String: String] = [:]
extendedRequest[paramSort] = sortDesc + " " + typeField + " " + field
let page = QBGeneralResponsePage(currentPage: 1, perPage: 100)
QBRequest.users(withExtendedRequest: extendedRequest, page: page, successBlock: { (response, page, users) in
}, errorBlock: { response in
})
```
```Objective-C theme={null}
NSString *field = @"created_at";
NSString *typeField = @"date";
NSString *sortDesc = @"desc";
NSString *sortAsc = @"asc";
NSString *paramSort = @"order";
NSMutableDictionary *extendedRequest = [NSMutableDictionary dictionary];
extendedRequest[paramSort] = [NSString stringWithFormat:@"%@ %@ %@", sortDesc, typeField, field];
QBGeneralResponsePage *page = [QBGeneralResponsePage responsePageWithCurrentPage:1 perPage:10];
[QBRequest usersWithExtendedRequest:extendedRequest.copy page:page successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
Here are the sort operators you can use to order the search results.
| Sort operator | Applicable to types | Applicable to fields | Description |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| asc | All types | id, full\_name, email, login, phone, website, created\_at, updated\_at,last\_request\_at, external\_user\_id | Search results will be sorted in ascending order by the specified field. |
| desc | All types | id, full\_name, email, login, phone, website, created\_at, updated\_at,last\_request\_at, external\_user\_id | Search results will be sorted in descending order by the specified field. |
## Retrieve users by ID
To get a list of users by ID for a current account, use the following code snippet.
```Swift theme={null}
let page = QBGeneralResponsePage(currentPage: 5, perPage: 10)
QBRequest.users(withIDs: ["21","22"], page: page, successBlock: { (response, page, users) in
}, errorBlock:{ (response) in
})
```
```Objective-C theme={null}
QBGeneralResponsePage *page = [QBGeneralResponsePage responsePageWithCurrentPage:5 perPage:10];
[QBRequest usersWithIDs:@[@"20", @"21"] page:page successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Retrieve user by login
To get a list of users by login for a current account, use the following code snippet.
```Swift theme={null}
QBRequest.user(withLogin: "amigo", successBlock: { (response, user) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest userWithLogin:@"amigo" successBlock:^(QBResponse * _Nonnull response, QBUUser * _Nonnull user) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Retrieve user by email
To get a list of users by email for a current account, use the following code snippet.
```Swift theme={null}
QBRequest.user(withEmail: "[[email protected]](/cdn-cgi/l/email-protection)", successBlock: { (response, user) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest userWithEmail:@"[[email protected]](/cdn-cgi/l/email-protection)" successBlock:^(QBResponse * _Nonnull response, QBUUser * _Nonnull user) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Retrieve users by full name
To get a list of users found by the server according to the search query, use the following code snippet.
Search **requires** min 3 characters.
```Swift theme={null}
QBRequest.users(withFullName: "Amigo", page: nil, successBlock: { (response, page, users) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest usersWithFullName:@"Amigo" page:nil successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Retrieve users by phone number
To get a list of users by phone number for a current account, use the following code snippet.
```Swift theme={null}
QBRequest.users(withPhoneNumbers: ["+4427123314"], page: nil, successBlock: { (response, page, users) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest usersWithPhoneNumbers:@[@"+4427123314"] page:nil successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Retrieve user by external user ID
If you have your own database with users (we call these databases as "external databases"), you can use External User ID (`ExternalID` field) in `QBUser` model to link users from QuickBlox with users from your external database.
```Swift theme={null}
QBRequest.user(withExternalID: 3789, successBlock: { response, user in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest userWithExternalID:3789 successBlock:^(QBResponse * _Nonnull response, QBUUser *user) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Retrieve users by tags
To get a list of users by tags for a current account, use the following code snippet.
```Swift theme={null}
QBRequest.users(withTags: ["iphone"], page: nil, successBlock: { (response, page, users) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest usersWithTags:@[@"iphone"] page:nil successBlock:^(QBResponse * _Nonnull response, QBGeneralResponsePage * _Nonnull page, NSArray * _Nonnull users) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Delete user
A user can delete himself from the platform.
```Swift theme={null}
QBRequest.deleteCurrentUser(successBlock: { (response) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest deleteCurrentUserWithSuccessBlock:^(QBResponse * _Nonnull response) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
## Reset user password
It's possible to reset a password via email.
```Swift theme={null}
QBRequest.resetUserPassword(withEmail: "[[email protected]](/cdn-cgi/l/email-protection)", successBlock: { (response) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
[QBRequest resetUserPasswordWithEmail:@"[[email protected]](/cdn-cgi/l/email-protection)" successBlock:^(QBResponse * _Nonnull response) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
Make sure to enable the email confirmation. This functionality allows application users to confirm their emails. If a user doesn't confirm the email, the emails won't be sent to this user. As a result, a password reset functionality won't work. To enable the email confirmation, proceed as follows:
1. Go to the **Dashboard => *YOUR\_APP* => Users => Settings => User registration confirmation** and check the box.
2. Click the **Save** button.
A password reset functionality is available for the Enterprise plan. [Contact the sales team](https://quickblox.com/enterprise/#get) for more details.
## Update user
Update a user profile by calling the `updateUser()` method. If you want to change your password, you need to provide 2 parameters: `password` and `oldPassword`. The updated user entity will be returned.
You must set `null` into the user's `password` field if you do not want to change your password, otherwise, you will need to add the user's old password to the `oldPassword` field.
You can update any other field of the user using the `updateUser()` method. Thus, the snippet below shows how to update a `tagList` and `customData` fields.
```Swift theme={null}
guard let currentUser = QBSession.current.currentUser else { return }
var customData:[String: String] = [:]
if let data = currentUser.customData?.data(using: .utf8),
let currentUserCustomData = try? JSONSerialization.jsonObject(with: data, options: []) as! [String : String] {
customData = currentUserCustomData
}
customData["name"] = "John"
customData["age"] = "31"
customData["city"] = "New York"
let updateUserParameter = QBUpdateUserParameters()
guard let customJSONData = try? JSONSerialization.data(withJSONObject: customData, options: .prettyPrinted) else { return }
updateUserParameter.customData = String(data: customJSONData, encoding: .utf8)
//example of custom data JSON string
let userCustomDataJsonStringExample = "{\"name\" : \"John\", \"age\" : \"31\", \"city\" : \"New York\"}"
updateUserParameter.tags = ["quickblox", "test", "QADev", "chat", "videochat", "webrtc", "conference"]
QBRequest.updateCurrentUser(updateUserParameter, successBlock: {response, user in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
QBUUser *currentUser = QBSession.currentSession.currentUser;
NSMutableDictionary *customData = [NSMutableDictionary dictionary];
if (currentUser.customData) {
NSData *currentUserJsonData = [currentUser.customData dataUsingEncoding:NSUTF8StringEncoding];
NSDictionary *currentUserCustomData = [NSJSONSerialization JSONObjectWithData:currentUserJsonData options:kNilOptions error:nil];
customData = currentUserCustomData.mutableCopy;
}
customData[@"name"] = @"John";
customData[@"age"] = @"31";
customData[@"city"] = @"New York";
QBUpdateUserParameters *updateUserParameter = [[QBUpdateUserParameters alloc] init];
NSData *jsonCustomData = [NSJSONSerialization dataWithJSONObject:customData options:NSJSONWritingPrettyPrinted error:nil];
NSString *jsonCustomDataString = [[NSString alloc] initWithData:jsonCustomData encoding:NSUTF8StringEncoding];
updateUserParameter.customData = jsonCustomDataString;
//example of custom data JSON string
NSString *userCustomDataJsonStringExample = @"{\"name\" : \"John\", \"age\" : \"31\", \"city\" : \"New York\"}";
updateUserParameter.tags = @[@"quickblox", @"test", @"QADev", @"chat", @"videochat", @"webrtc", @"conference"];
[QBRequest updateCurrentUser:updateUserParameter successBlock:^(QBResponse * _Nonnull response, QBUUser * _Nonnull user) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
| Field | Required | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tags | no | User tags. An array of Strings. A tag must include alphabetic characters only. The tag must be at least 3 and no more than 15 characters long. There are no spaces in the tag format. For example, the "tagOne" format is correct while the "tag one" format is incorrect. The maximum number of tags is 10. If more than 10 tags are provided, an error is returned: tag list should contain maximum 10 tags. |
| customData | no | User custom data. Should be a String. You can convert any data types to String, or example, JSON, XML, etc. |
## Set user avatar
To set a user avatar, just upload a file to the QuickBlox cloud storage and connect it to the user.
To upload the file to the QuickBlox cloud storage, just convert the file to the date format and upload it to the QuickBlox cloud storage by calling the `tUploadFile(fileName:contentType:isPublic:)` method. In the response, the `uploadedBlob` object is returned by the server. Get the blob UID from the `uploadedBlob` object.
To connect the file to the user, set the blob UID in the `customData` field of the `user` model and call the `updateCurrentUser()` method. As a result, the user avatar gets updated.
```Swift theme={null}
let image = UIImage(systemName: "person.circle")
guard let imageData = image?.pngData() else {
return
}
let fileName = "avatar.png"
let contentType = "image/png"
let isPublic = true
QBRequest.tUploadFile(imageData, fileName: fileName, contentType: contentType, isPublic: isPublic, successBlock: { (response, uploadedBlob) in
let parameters = QBUpdateUserParameters()
parameters.blobID = uploadedBlob.id
QBRequest.updateCurrentUser(parameters, successBlock: { (response, user) in
}, errorBlock: { (response) in
})
}, statusBlock: { (request, status) in
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
UIImage *image = [UIImage systemImageNamed:@"person.circle"];
NSData *imageData = UIImagePNGRepresentation(image);
NSString *fileName = @"avatar.png";
NSString *contentType = @"image/png";
BOOL isPublic = TRUE;
[QBRequest TUploadFile:imageData fileName:fileName contentType:contentType isPublic:isPublic successBlock:^(QBResponse * _Nonnull response, QBCBlob * _Nonnull uploadedBlob) {
QBUpdateUserParameters *parameters = [[QBUpdateUserParameters alloc] init];
parameters.blobID = uploadedBlob.ID;
[QBRequest updateCurrentUser:parameters successBlock:^(QBResponse * _Nonnull response, QBUUser * _Nonnull user) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
} statusBlock:^(QBRequest * _Nonnull request, QBRequestStatus * _Nonnull status) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
Pass the following arguments to the `updateCurrentUser()` method.
| Argument | Required | Description |
| ---------- | -------- | ----------------------------------------------- |
| parameters | yes | Specifies parameters fields that should be set. |
## Get user avatar
Now, other users can get your avatar by calling the `downloadFile(withUID:)` method.
```Swift theme={null}
let userAvatarImageView = UIImageView()
let user = QBSession.current.currentUser
QBRequest.blob(withID: user.blobID, successBlock: { (response, blob) in
guard let blobUID = blob.uid else {return}
QBRequest.downloadFile(withUID: blobUID, successBlock: { (response, fileData) in
if let image = UIImage(data: fileData) {
userAvatarImageView.image = image
}
}, statusBlock: { (request, status) in
}, errorBlock: { (response) in
})
}, errorBlock: { (response) in
})
```
```Objective-C theme={null}
UIImageView *userAvatarImageView = [[UIImageView alloc] init];
QBUUser *user = QBSession.currentSession.currentUser;
[QBRequest blobWithID:user.blobID successBlock:^(QBResponse * _Nonnull response, QBCBlob * _Nonnull tBlob) {
[QBRequest downloadFileWithUID:tBlob.UID successBlock:^(QBResponse * _Nonnull response, NSData * _Nonnull fileData) {
UIImage *image = [UIImage imageWithData:fileData];
userAvatarImageView.image = image;
} statusBlock:^(QBRequest * _Nonnull request, QBRequestStatus * _Nonnull status) {
} errorBlock:^(QBResponse * _Nonnull response) {
}];
} errorBlock:^(QBResponse * _Nonnull response) {
}];
```
| Argument | Required | Description |
| --------- | -------- | ----------------------- |
| avatarUID | yes | Blob unique identifier. |