User

Identity

Amity SDK's do not store or manage any user data. This means that you do not have to import or migrate existing user profiles into the system, user management should be handled by your application code. Instead, every user is simply represented by a unique userID, which can be any string that uniquely identifies the user and is immutable throughout its lifetime.

A database primary key would make an ideal userID. Conversely, something like username or emails is not recommended as those values may change over time.

If you wish to assign additional permissions for a user, for example, moderation privileges or different sending limits, you can provide an array of roles to assign to this user. Roles are defined in the admin panel and can be tied to an unlimited number of users. Once again, Amity does not store or manage any user data, which means you do not have to import or migrate existing users into the system. It also means that Amity cannot provide user management functionalities like list of users, or limit actions of certain users (e.g. user permissions). Instead, these functionalities should be handled by the rest of your application's capabilities and your server.

Description of Users

Name	Data Type	Description	Attributes
userId	string	The id of this user
roles	Array.<string>	A list of user's roles
displayName	string	The display name of the user
flagCount	integer	The number of users that have flagged this user
metadata	Object	The metadata of the user
hashFlag	Object	A hash for checking internally if this user was flagged by the user
createdAt	date	The date/time the user was created at
updatedAt	date	The date/time the user was updated at
isGlobalBan	Boolean	Flag that indicates if the user is globally banned. True means the user is globally banned. Note: This is not yet supported for Typescript
avatarCustomUrl	String	Custom Url provided for this user avatar
isDeleted	Boolean	Flag that indicates if the user is deleted

Though the SDK does not store and should not be responsible for the handling User profile data for your application; We do provide tools to make some surface-level queries and searches for existing user accounts. With the help of our AmityUserRepository class, you will be able to list all the users, search for list of users whose display name matches your search query and get AmityUser object from user ID.

User Repository

Some SDKs keep the user methods in a UserRepository class. Before calling any User methods, you must first instantiate a repository instance.

iOS

Android

JavaScript

import { UserRepository } from '@amityco/js-sdk';
const userRepo = new UserRepository();

Flutter

Get User Details

Each user consists of a userId and displayName. The userId is immutable once the account is created, however the displayName can be updated at all times.

iOS

Each User consists of a userId and displayName. The userId is immutable once the account is created. However, the displayName can be updated at all times. AmityUserRepository provides a convenient method getUser(_:) which maps user id to a particular AmityUser object. It returns a live AmityObject<AmityUser> which you can observe too. It accepts one parameter userId which is the ID of the user.

let userObject = userRepository.getUser("some-user-id")
userObject.observe { (user, error) in
    // you can access AmityUser object as user.object here
}

Android

Below is a sample code for fetching a single user:

JavaScript

Follow the below code to retrieve a user object:

import { UserRepository } from '@amityco/js-sdk';

const liveObject = UserRepository.getUser('userId');
liveObject.on('dataUpdated', user => {
  // user is successfully fetched
});

Get Single User

The User Repository provides a method to get a single user. It returns a LiveObject which you can observe.

userRepo.userForId('user123')

You can also use the code below to get one user:

let liveUser = UserRepository.getUser("some-user-id")
userObject.on(“dataUpdated”, model => {
   // you can access user object as model here
  console.log(model.userId, model.displayName)
})

User Model

{
    userId -> string
    displayName -> string | undefined
    avatarFileId -> string | undefined
    avatarCustomUrl -> string | undefined
    description -> string | undefined
    roles -> string[]
    permissions -> string[] 
    metadata -> object | undefined
    createdAt -> Date
    updatedAt -> Date
    hashFlags -> object | null
    flagCount -> number 
}

Get All Users

The User Repository provides a method to get a list of all users, which will be returned as a LiveCollection:

userRepo.getAllUsers()

This method takes an optional sortBy parameter which must be a UserSortingMethod - these include displayName, firstCreated, and lastCreated:

import { UserSortingMethod } from '@amityco/js-sdk'

userRepo.getAllUsers(UserSortingMethod.DisplayName)

TypeScript

Get Single User

Follow the below code get an user from the id.

Get Multiple Users

Follow the code to get multiple users from their ids ​

Observe Users

TypeScript SDK provides a convenient way get a single user using observeUser.

Flutter

Create User

Create a new user into the system by logging in as shown below.

Note:

• When a user ID is created, it can be up to 50 characters in length.

• When user edits / adds their display name, it can be up to 100 characters in length.

iOS

Android

JavaScript

import AmityClient from “@amityco/js-sdk”

const amityClient = new AmityClient({ apiKey, apiEndpoint })
amityClient.registerSession({ userId, displayName, avatarFileId })

TypeScript

Flutter

1. If user doesn’t exist, it will be created upon calling this method.

2. If displayName is passed, it will update the user directly.

3. If displayName is passed, but secured mode is enabled, the values will be ignored.

For more details on connecting client such as secure mode, refer to the Getting Started session.

Delete User

When a user is deleted, the account cannot be reactivated in any case. There is no way to recover the data as it is permanently deleted.

Refer Delete User section for more information on what happens when a user is deleted.

Ban User

You can ban a user globally. When users are globally banned, they can no longer access Amity's network and will be forcibly removed from all their existing channels.

Refer global ban documentation for instructions on how to globally ban a user.

Search User

Note: If the user ID or display name you’re searching for contains special characters, you’ll need to enter the whole keyword in order for it to appear in the search results.

iOS

AmityUserRepository contains another convenient method searchUser(_:_:) which allows you to query for any particular user using their display name. It provides you with a collection of AmityUser whose display name matches with your search query. It accepts two parameters. The first one is the display name that you want to search for and the second one is sort option which is AmityUserSortOption enum.

Search users by display name

Android

AmityUserRepository provides searchUserByDisplayName() method which allows you to query for users using their display name. It provides you with a LiveCollection of AmityUser whose display name matches your search query. AmityUserSortOption is an optional parameter.

The code above will provide you with the list of users which matches with display name "Brian".

JavaScript

The User Repository provides a method to search for users by their display name. The result of this search is returned as a LiveCollection.

userRepo.searchUserByDisplayName('Test User 1')

The above example searches for all users whose display names start with "Test User 1".

Note: Search is case sensitive.

TypeScript

The queryUsers provides a way to search for users by their display name.

Query Users

iOS

AmityUserRepository provides a convenient method getUsers(_:) to fetch all users. This method will return AmityCollection<AmityUser>. You can observe changes in collection, similar to message or channel. The method accepts AmityUserSortOption enum as a parameter. The list can be sorted by displayName, firstCreated or lastCreated.

Query users

The above code lists the users sorted by displayNameAmityUserRepository provides a convenient method getUsers() to fetch all users. You can observe for changes in collection, similar to message or channel. The method accepts AmityUserSortOption as an optional parameter.

Android

AmityUserSortOption has 3 possible enum types

1. AmityUserSortOption.DISPLAYNAME Sort by displayName

2. AmityUserSortOption.FIRST_CREATED Sort by firstCreated

3. AmityUserSortOption.LAST_CREATED Sort by lastCreated

JavaScript

There is a queryUsers method in the user repository for you to use. The major difference between this new method against the older methods getAllUsers and searchUserByDisplayName is that queryUsers allows the 2 functionalities at once.

For example, as before you could not search for "users starting with k ordered by displayName" since the sortBy and keyword were two separated functionalities.

We also added a convenient filter parameter which allows to refine your search by users who've been reported by other users of your network.

const liveUserCollection = UserRepository.queryUsers({
    keyword?: string, 
    filter?: 'all' | 'flagged', 
    sortBy?: 'lastCreated' | 'firstCreated' | 'displayName'
})

// filter if flagCount is > 0
// lastCreated: sort: createdAt desc 
// firstCreated: sort: createdAt asc 
// displayName: sort: alphanumerical asc

liveUserCollection.on(“dataUpdated”, models => {
  models.map(model => console.log(model.userId))
})

TypeScript

Follow the below code for quering users

Flutter

Update User Information

You can update information related to current user such as display name, avatar, user description, metadata, etc. TheamityClient class contains updateCurrentUser: method which allows you to update the current user's information.

iOS

Update the current user data

Android

JavaScript

The updateCurrentUser method accepts the following optional parameters:

• displayName - user's display name

• description - user's description

• avatarFile - file ID of the user's avatar

• avatarCustomUrl - custom url of the user's avatar

• roles - user's role

• metadata - user's metadata

Below is a sample code on how to update the current user's display name, description, and metadata. This method returns a promise. If the update is successful, the method will return true, else it throws an error.

const myMetadata = { whatever: “i want”, toPass: “is ok” }

const success = await amityClient.updateCurrentUser({
  displayName: "Batman",
  description : "Hero that Gotham needs",
  metadata: myMetadata,
})

Flag/Unflag Users

To flag a user, call the following method:

userRepo.flag({ userId: 'user123' })

To unflag a user, call the following method:

userRepo.unflag({ userId: 'user123' })

Both of these methods return a promise. This means that they can be chained with .then and .catch handlers:

userRepo.flag({ userId: 'user123' })
    .then(() => {})
    .catch(() => {})

TypeScript

Flag/Unflag Users

To flag a user, call the following method:

To unflag a user, call the following method:

To check if the user is flagged by the current user:

Flutter

Avatars

You can upload an image and set it as an avatar for the current user.

iOS

First, you need to upload image using AmityFileRepository and then update the image info.

Step 1 — Upload an image:

Create AmityFileRepository

Upload an image with AmityFileRepository

Step 2 — Passing AmityImageData from step 1 into the builder, and call user update API.

Update the current user avatar

If you have an avatar present in your current system/server and just want to integrate that existing avatar to AmitySDK, you can just set the URL for the avatar directly.

Update user custom avatar

Note: getAvatarInfo provides the information associated with a particular Avatar

Android

First, you need to upload image and then update the image info. If you have an avatar present in your current system/server and just want to integrate that existing avatar to AmitySDK, you can just set the URL for the avatar directly.

If you have an avatar present in your current system/server and just want to integrate that existing avatar to AmitySDK, you can just set the URL for the avatar directly.

JavaScript

Either you wish to let us handle your user's avatar, or if you already have a system for it we got you covered. The 2 properties avatarFileId and avatarCustomUrl answer those two use-cases separately.

You can easily retrieve the url of a file from our FileRepository object and use it to display in your app later on. Here's an example in React:

import { useState, useEffect, useMemo } from 'react'

// our image component
const FileImage = ({ fileId }) => {
  const [fileUrl, setFileUrl] = useState()

  useEffect(() => {
    const liveObject = FileRepository.fileInformationForId(fileId)

    liveObject.on('dataUpdated', model => setFileUrl(model.fileUrl))
    liveObject.model && setFileUrl(liveObject.model.fileUrl)

    return () => {
      liveObject.dispose()
    }
  }, [fileId])

  return fileUrl ? <img src={fileUrl} /> : null
}

// our user component
const UserHeader = ({ userId }) => {
  const [user, setUser] = useState({})

  const displayName = useMemo(
    () => user?.displayName ?? user?.userId,
    [user],
  )

  useEffect(() => {
    const liveObject = UserRepository.getUser(userId)

    liveObject.on('dataUpdated', setUser)
    liveObject.model && setUser(liveObject.model)

    return () => {
      liveObject.dispose()
    }
  }, [userId])

  return (
    <div>
     {user.avatarFileId && <FileImage fileId={user.avatarFileId} />}
     {user.avatarCustomUrl && <img src={user.avatarCustomUrl} />}
    </div>
  )
} 

TypeScript

You can easily retrieve the url of a file using observeFile and use it to display in your app later on. Here's an example in React:​

Flutter

For more information please go to User & Content Management