This page consists of three components:

• Recommended communities

• Top trending communities

• Categories

Features

Features

Features

The UiKitProvider

At the core of your project, you will need to import and decorate your application with the UiKitProvider.

import { UiKitProvider } from ‘@amityco/ui-kit’

export default function App() {
  return <UiKitProvider>
    <YourApp />
  </UiKitProvider>
}

Using the UIKit

You can use the UIKit components with this code:

<AmityUiKitProvider key={userId} apiKey={apiKey} userId={userId}>
    <AmityUiKitSocial />
</AmityUiKitProvider>

Our community group functionality within UIKit allows you to explore social features and see how they will look in your app.

To allow for more customization, we have now open sourced our UI Kits and deprecated the packaged UI Kit version that was previously available.

With open source, developers have more flexibility and greater customization options, allowing you to have complete control over the visual style. Open sourcing allows for more transparency and visibility, and enables contributions from a greater developer community in terms of good design, implementation, code improvement, and fixes, translating into a better product and development experience.

To ensure that you continue to receive the latest features and updates, we encourage you to migrate over to the open source version. This guide will help you:

• Migrate Web Open Source UI Kit with an existing project

• Modify Open Source UI Kit to customize the visual style

• Get latest Open Source UI Kit updates

Migrate Web Open Source UI Kit with Existing Project

Remove Existing Dependencies

If you’ve never used the packaged Web UI Kit before, you may skip this step and proceed to the next step.

If you’re migrating over to the open-source version, you’ll need to remove and unlink the packaged UI Kit from your project before installing the open source source code.

Migrate Open Source Web UI Kit

There are several ways for you to integrate the open-source Web UI Kit into your projects, depending on your workflow. We recommend installing from npm, however we’ve also included instructions to install via Git Submodule.

Method 1: Installing via npm

• Clone or download source code from an open-source Github repository

git clone git@github.com:AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource.git

• After downloading the source code, navigate to the directory where the source code was installed:

cd Amity-Social-Cloud-UIKit-Web-OpenSource

• Run npm i to install package dependencies

• Run npm build

• Run npm link

• Lastly, import (link) the UI Kit into your project by running the following command

npm link @amityco/ui-kit-open-source --install-links

Woohoo! All set! Now let’s try a sample code to get you started with our UI Kit:

import "./styles.css";
import { AmityUiKitProvider, AmityUiKitSocial } from "@amityco/ui-kit-open-source";
const userId = "<your USER ID here>";
const apiKey = "<your API key here>";
export default function App() {
return (
<div className="App">
<AmityUiKitProvider
key={userId}
apiKey={apiKey}
userId={userId}
displayName={userId}
>
<AmityUiKitSocial />
</AmityUiKitProvider>
</div>
);
}

Method 2: Installing via git submodule

• First, create a new React project

• Create a new repository using git init inside your root directory

• Select the path where you want to clone the submodule or use cd src

• Add AmityUIKit open source into your git repository with git submodule command as shown below

git submodule add
 https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource
 "ui-kit"

• Navigate to the directory where the source code was installed

cd ui-kit

• Run npm i to install package dependencies

• Run npm run build

• Install and configure babel transcompiler, then create babel.config.js at the root of your project. Your project structure should be similar to the screenshot below:

• Add “babelrcRoots” option into your babel.config.js file. If you installed the source code in a different path, replace “./src/ui-kit” with the path where you installed the UI Kit.

"babelrcRoots": [ "./", "./src/ui-kit"]

• Once you’ve installed and created the babel configuration, your configuration may look like this:

module.exports = {
"presets": [
"@babel/preset-react",
"@babel/preset-env"
],
"plugins": [
"@babel/plugin-proposal-class-properties",
"@babel/plugin-proposal-object-rest-spread"
],
"babelrcRoots": [ "./", "./subModules/ui-kit" ]
}

• Next, go back to your project’s root directory and run the following commands:

  • cd node_modules/react

  • npm link

• Then, go to the ui-kit folder and run npm link react

• Finally, go back to the root directory of your project and run npm run start

Woohoo! All set! Now let’s try a sample code to get you started with our UI Kit

import "./styles.css";
import { AmityUiKitProvider, AmityUiKitSocial } from "@amityco/ui-kit-open-source";
const userId = "<your USER ID here>";
const apiKey = "<your API key here>";
export default function App() {
return (
<div className="App">
<AmityUiKitProvider
key={userId}
apiKey={apiKey}
userId={userId}
displayName={userId}
>
<AmityUiKitSocial />
</AmityUiKitProvider>
</div>
);
}

Modifying Web Open Source UI Kit

You can modify the Web open source UI Kit to customize behaviors to fit your needs. To modify the code, simply copy and paste it into your local machine.

We recommend that you first fork the repository before starting any customization work, so that it will be easier to merge the code with the next version update that we provide from the main repository.

Reference on forking: https://docs.github.com/en/get-started/quickstart/fork-a-repo

Get Latest UI Kit Open Source Updates

To update to the latest version of the UI Kit, you can pull the latest commit of the git submodule.

git clone git@github.com:AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource.git
cd ..
npm i
npm build
npm link

Introduction

Our Social UIKit for Amity Social Cloud is a development kit with a user interface to enable fast integration of standard Amity Social features into new or existing applications. Themes allow you to apply your style through colors and fonts.

We have now open sourced Amity UIKit so you will have complete control of the visual style of your Chat and Social application with endless customizations. Amity UIKit open source is now available in our Github repository.

To customize Amity UIKit open source, download the source code and apply the customizations in the forked source code. Once you fork our UIKit source code separately, you basically own the product so you are free to customize and build it for your specific use cases.

We recommend that you use Amity UIKit open source when:

1. The standard UIKit is not applicable to your use case .

2. You want to use an Amity Chat or Social SDK feature which is not yet supported in our standard UIKit.

Please note that we will extend only a limited support once you customize our UIKit open source since we won’t be able to fully know your code once you fork it.

Documentation

We are using the Amity UIKit open source wiki for any documentation related to Amity UIKit open source.

For our standard UIKit, you can refer to the documentation here.

Community guidelines

If you would like to suggest improvements on the source code, you can submit a pull request. If you find bugs or would like to request features, you can create an issue. Please note that not all changes and requests will be approved but they will be assessed in due course.

For more information on these guidelines, you may refer to the Amity UIKit open source wiki or you may go directly to these related pages:

• Customizing Amity UIKit Open Source

• Contributing to Amity UIKit Open Source

• Submitting fixes and feature requests

Benefits

• Easy Installation

• Fully featured social experience with minimal amount of code.

• Customize targeted UX flows, specific views and respond to user interactions to tailor a user experience for just your application

Requirements

• React 16+

• React hooks

Key Concepts

Architecture

The UIKit is built on the foundation of the Amity Social Cloud API. We added a UI layer to speed up product development efforts of your application. At the core, it is leveraging the same Channel, Messaging concepts, subscribing to live objects while adding a UIKit to accelerate product delivery and UI that delivers great user experience for companies wanting to deploy messaging and other functionalities.

In the current state, our Social module can be used. This module can be integrated into your application with ease using this documentation.

Setup API Key

AmityUIKitProvider requires an API key. You need a valid API key to begin using the UIKit. Please find your account API key in Amity Social Cloud Console.

After logging in Console:

1. Click Settings to expand the menu.

2. Select Security.

3. In the Security page, you can find the API key in the Keys section.

export default function Wrapper({ apiKey, apiEndpoint, userId, displayName }) => {
  return (
    <UiKitProvider
      apiKey={apiKey}
      apiEndpoint={apiEndpoint}
      userId={userId}
      displayName={displayName || userId}
    >
      <App />
    </UiKitProvider>
  )
}

Specify Endpoints Manually (Optional)

You can specify endpoints manually via optional parameters. API endpoints for each data center are different so you need to adjust the endpoint accordingly.

We currently support multi-data center capabilities for the following regions:

Unregister

In the event that your user logs out, you should explicitly unregister the user from the SDK as well, to prevent the current device from receiving any unnecessary or restricted data.

export default function Wrapper({ apiKey, apiEndpoint, userId, displayName }) => {
  const ref = useRef();

  const handleConnect = () => ref.current.connect();
  const handleDisconnect = () => ref.current.disconnect();

  const handleConnected = () => console.log(“connected”);
  const handleDisconnected = () => console.log(“disconnected”);

  return (
    <UiKitProvider
      ref={ref}
      apiKey={apiKey}
      apiEndpoint={apiEndpoint}
      userId={userId}
      displayName={displayName || userId}
      onConnected={handleConnected}
      onDisconnected={handleDisconnected}
    >
      <App
         connect={handleConnect}
         disconnect={handleDisconnect} />
    </UiKitProvider>
  )
}

Using the default theme

AmityUIKit uses the default theme as part of the design language.

Theme customization

Without customization, the UIKit already looks good. However, if you wish to customize the theme, you can declare changes to both colors and typography. The tables below shows the default theme values.

Colors

UIKit uses a small set of declared colors to simplify the design task for developers. These colours are automatically rendered at appropriate shades to communicate states and interaction to the users.

Typography

This is what the structure looks like if you are just using the default theme.

const defaultTheme = {
  palette: {
    alert: '#FA4D30',
    base: '#292B32',
    primary: '#1054DE',
    secondary: '#FFD400',
    tertiary: '#FF305A',
    neutral: '#17181C',
    highlight: '#1054DE',

    system: {
      borders: '#ebecef',
      background: '#fff',
    },
  },

  typography: {
    global: {
      fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, Arial, sans-serif',
      fontStyle: 'normal',
    },
    headline: {
      fontWeight: 600,
      fontSize: '20px',
    },
    title: {
      fontWeight: 600,
      fontSize: '16px',
    },
    body: {
      fontWeight: 'normal',
      fontSize: '14px',
    },
    bodyBold: {
      fontWeight: 600,
      fontSize: '14px',
    },
    caption: {
      fontWeight: 'normal',
      fontSize: '12px',
    },
    captionBold: {
      fontWeight: 600,
      fontSize: '12px',
    },
  },
};

To customize your own theme:

const myTheme = {
  //...partial representation of the defaultTheme
}

<AmityUiKitProvider theme={myTheme} ... />

Custom theme will be applied on top of default theme so you don't need to provide all the values. The default values will be used if there are some customizations that are missing.

The community section consists of three components:

Component Customization Limitation

Amity UIKit provides already built UI elements on a single page. You can change the appearance such as color and typography in the . However, the UIKit does not allow you to replace these small components with other views. In addition, you cannot modify the view hierarchy inside the page.

The Community Newsfeed consists of:

Features

Usage

First, you need to get your api key and authToken from the authorization server. Then, to render the whole social kit:

To render the user feed only:

Features

Community settings can be accessed by clicking the Edit profile button in the Community profile page.

Features

Features

Feature and Component

Features

Features

Features

Feature

Features

Features

Edit Post Pop-up

Default post creation stage

Features

Types of Posts

1. Text

2. Text and Image

Creating a text and image post

After posting a text and image post

3. Text and File

Creating a text and file post

After posting a text and file post

4. Text and Video

Creating a text and video post

After posting a text and video post

5. Poll Post

Default poll creation page

Poll post

Poll voting

Mention users in a poll post

5. Livestream Post

Mention users in a livestream post

Out Web UIKit provides the livestream recording feature that allows you to record livestreams and broadcast simultaneously in real-time. You can also play historical streams when the livestream ends.

This section describes the livestream viewing feature in detail. Refer to our Livestream documentation to create a livestream in console.

A livestream post can be viewed in the following feeds:

• Community feed

• User feed

• Global feed

• Content feed

You will be able to see the livestream post and interact with it as soon as the livestreamer starts streaming.

Creating a Livestream Post

Creating a livestream can be done in Console. There are two parts before you can create the livestream post. First, create the livestream. You need to have a third-party software installed such as OBS or any livestreaming tool. Then, create the post.

Create livestream

1. In Console, go to Livestream menu.

2. In Streaming management page, click .

3. In Create new stream pop-up, provide the title, description, and thumbnail.

4. Click OK to submit.

5. In Streaming management list, select the stream that you created.

6. In Streaming details page, copy the Server URL. Paste it in your livestreaming software and start the livestream.

Create livestream post

1. In Console, go to Posts menu.

3. In Create livestream post pop-up, provide the Target type, Target ID, and Stream ID.

   • Target type - can be Content, Community, or User

   • Target ID - community ID or user ID of the community or User where you want to post the livestream

   • Stream ID - search for the streamId value in the stream's Raw model in Streaming details

4. Click OK to submit.

Viewing a livestream post

Live

Other viewers can watch your livestreaming while you are simultaneously recording it. They will see a LIVE indicator on the video.

Tapping the play button in the livestream post will play the video in a full screen mode.

The LIVE indicator on the upper left corner of the video indicates that the video is currently streaming while you are watching it.

Livestream ended

After ending your livestreaming, the playback video may not be available instantly for viewers to see while it is still in the process of producing the playback video. The viewers will see a message that the playback will be available for watching shortly.

Playback

When the playback video is already available for viewing, a RECORDED indicator is shown on the video post.

Idle state

The livestream may be in idle state. This happens when you delete the livestream in console or or other issues that will not enable the livestreaming to start. The viewer will see a message that the stream is currently unavailable.

Read-only mode

A livestream post will have the same privacy and access controls as with the other posts. This means that users without the permission, such as those who are not members of the community, won’t be able to view the livestreaming/playback video in a private community. If the community is public, non-members can view the post as read only so they won't be able to interact with it.

Components

Below are the different views of the community profile page depending on your role and permission.

Moderator views

Non-community members

Features

Features

Features

There are two types of user profiles:

1. Your own profile

1. Profile of another user

Components

• User feed

Features

Features

import { FeedType, PostTargetType } from '@amityco/js-sdk'

const CommunityFeed = ({ communityId, currentUserId, isNewCommunity }) => {
return (
            <AmityUiKitFeed
                        targetType={PostTargetType.CommunityFeed}
                        targetId={communityId}
                        feedType={FeedType.Published}
            />
    )
}

Default User Feed

This view allows you to see and interact with the feed content normally. This applies when the Privacy setting is Public.

Private user feed

This view blocks any user to see the target user's feed content. This view only exists if the Privacy setting is Private.

Features

This feature allows the transfer of moderator roles and blocks the last moderator to leave a community without transferring the role to other members, giving continuity to groups and creating a clear assignment to future moderators.

How it works

When a moderator leaves the community and there are no other moderators left, a pop-up will show that the moderator needs to nominate other members before leaving the community.

The moderator needs to promote a member to a moderator to transfer the moderator role to that member.

After a new moderator is selected, the moderator who wishes to leave can now leave the community.

Features

In the Followings page you can see the list of users you are following.

In the Followers page you can see the list of users who follow you.

UIKit provides a way to render your own UI and override the default UIKit behavior.

Feature

• Post rendering

Manage your profile settings on this Profile Settings page.

Edit Profile

Feature

UIKit provides a way to use your own UI to replace the default UIKit components.

Feature

• Using your own like button for posts

In this section, you can see all your pending follow requests. You can either Accept or Decline a request.

If a user in your pending list has withdrawn the request, the system error below will show when you accept or decline the user's follow request.

Features

Usage

You need to pass all your custom components into AmityUiKitProvider using customComponents prop.

import { AmityUiKitProvider } from '@amityco/ui-kit';

function CustomPostLikeButton({ onClick, isActive, isDisabled }) {
  return (...);
}

function MyApp() {
  return (
    <AmityUiKitProvider
      customComponents={{
        PostLikeButton: CustomPostLikeButton,
        anotherComponentId: AnotherCustomComponent,
      }}
    >
    </AmityUiKitProvider>
  );
}

Message list page header

Features

Message list

Feature

Compose Message

Features

Features

Text Message Bubble

Features

Custom Post Rendering

UIKit provides default renderers for the core data types: text, image, and file. It also provides a way to render your own UI for your custom post.

Post Structure

A single post UI is composed of 1 or more blocks. This allows reusability of block components such as header or footer which can be shared by different kinds of posts.

This is an example of an image post which contains three tableview cells. Top cell represents the header, middle cell contains content and bottom cell is footer cell.

Creating UI for custom posts

First, you need to create your custom renderer.

Then, you need to pass your renderer into AmityUiKitProvider

When a user clicks on the user profile avatar at the post creator area, UIKit will open User profile page.

However, you can intercept the event and define your own logic following the example below.

Usage

Let’s say you want to override the default logic and open your own modal showing the user profile instead of navigating to the user profile page.

function openUserProfileModal(userId) {
  ...
}

function MyApp() {
  return (
    <AmityUiKitProvider
      actionHandlers={{
        onClickUser: userId => openUserProfileModal(userId),
      }}
    >
      ...
    </AmityUiKitProvider>
  );
}

Features

Custom Event Handler

There are many pages and actions on AmityUIKit. Pages can be nested inside others and it would be hard for overriding events on the nested pages. In order to solve this problem, we provide EkoEventHandler which is a behavior controller for actions that happen in UIKit.

Supported Events

Usage

To pass handlers into UIKit you need to set ‘actionHandlers’ prop for AmityUiKitProvider. All handlers are optional. If any is not passed, UIKit will use its own internal implementation.

You can access any action handler using the useAmityNavigationhook.

UIKit offers you a ready-to-use integration solution with the SDK Role & Permission feature. There is a default Community level role named Moderator.