Introduction

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

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

To customize Social Plus 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 own the product so you are free to customize and build it for your specific use cases.

We recommend that you use Social Plus UIKit open source when:

1. The standard UIKit does not apply to your use case.

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

Please note that we will extend only 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 Social Plus UIKit open-source wiki for any documentation related to Social Plus UIKit open-source.

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

Community Guidelines

If you would like to suggest improvements to 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 Social Plus UIKit open-source wiki or you may go directly to these related pages:

• Customizing Social Plus UIKit Open Source

• Contributing to Social Plus UIKit Open Source

• Submitting fixes and feature requests

Benefits

• Easy Installation.

• Fully featured chat experience with minimal coding.

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

Requirement

• iOS 11.0 or higher

• Swift 5

• Xcode 11.7

Implementation Strategies

The UIKit API provides several strategies to integrate with your application.

Page Presentation

• Use the UIKit as is.

• Integrate the Chat experience in the least amount of effort.

Page Presentation customized

• Add a custom theme to the default implementation of the UIKit.

• Complete control of the visual style of Chat UI by implementing declarative styles (fonts and colors) for your user interface.

Page Integration

• Use key components from the UIKit SDK and integrate them directly into your application.

• Add the Chat UI to your existing design.

Key Concepts

Architecture

The UIKit is built on the foundation of the Social Plus API while adding a UI layer to speed product development efforts. At the core, it is leveraging the same Channel and messaging concepts, subscribing to live objects whilst adding a UIKit to accelerate product delivery and UI that delivers great user experience for companies wanting to deploy messaging.

In the current state, there are two modules that can be used. You can follow the steps below. These two modules can be integrated into your application easily in no time.

iOS UI Kit Migration Instructions

To allow for more customization, we have now open-sourced our UIKits 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 typical development.

To ensure that you continue to receive the latest features and updates, we encourage you to move off the managed UI Kit to the Open Source UI Kit. This guide will show you how to:

• Migrate Open Source UI Kit with an existing project

• Modify the Open Source UI Kit to customize the visual style

• Get the latest Open Source UI Kit updates

Migrate iOS Open Source UI Kit with Existing Project

Remove existing dependencies

If you've never used UI Kit, you may skip this step and proceed to the next step.

If you're integrating the UI Kit with an existing project, you'll need to remove and unlink the managed UIKit from your project before proceeding with the integration.

Migrate to iOS UIKit Open Source

There are several ways for you to migrate the open-source iOS UI Kit into your projects, depending on your workflow. One way that we recommend is via Git Submodule. This instruction assumes that the app project is already set up with a Git repository.

1. Add the git submodule of Social Plus UIKit open source into your git repository.

git submodule add https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource

For new users:

If you are just starting to use Open Source UIKit or already using the latest version of Open Source UIKit (i.e. v3.12.0) from the old Repository, We suggest you start pulling changes from the new repository instead.

In this case,

• If you have forked the old open-source UIKit repository, we suggest you fork the new repository and use that instead.

For Old Users:

If you are using an older version (< 3.12.0) of open-source UIKit, we suggest you upgrade to the latest version of UIKit as soon as possible. Once you are caught up to version 3.12.0, please migrate to use the new repository instead.

1. Create an Xcode Workspace, and then add both MyApp.xcodeproj and AmityUIKit.xcodeproj together under the same workspace.

3.SocialPlusUIKit links with other dependencies such as SocialPlusSDK, Realm etc through SharedFrameworks which is a Swift Package.

Step 1: Reset the Package Cache of your Application Target i.e. YourApp.xcodeproj. [If you are installing AmityUIKit for the first time, you can skip this step]

Select App Target In Xcode Project -> Select File Menu for Xcode-> Packages -> Reset Package Cache

Step 2: Link SharedFrameworks & AmityUIKit.framework to YourApp.xcodeproj target as shown below.

4. On MyApp.xcodeproj, let’s try importing Social Plus UIKit / Social Plus SDK and calling some APIs. You should be able to compile and run the app.

Modify iOS Open Source UI Kit

You can modify the iOS 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.

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

Get Latest iOS Open Source UI Kit Updates

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

cd https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource
git pull origin master
cd ..
git add .
git commit -m “Update ios uikit opensource submodule”
git push origin master

This section is about installing managed UIKit through the dependency manager. If you have already installed our Open Source UIKit, you can skip this section.

Create a project

Go to Xcode and create a project for iOS.

1. Enter a project name

2. Select Swift as your language option

Using Dependency Manager

Social Plus UIKit supports installation via dependency managers, we highly recommend SwiftPM installation as the best practice.

• SwiftPM

• Cocoapods

• Carthage

SwiftPM Installation

To integrate Social Plus UIKit into your project via SwiftPM, please follow the instructions below.

• Add a Package Dependency

Enter the repository URL to search the package, and choose to install Social Plus UIKit.

https://github.com/AmityCo/Amity-Social-Cloud-UIKit-iOS-SwiftPM

Carthage Installation

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate the Social Plus UIKit. First, add the following to your Cartfile.

binary "https://raw.githubusercontent.com/AmityCo/Amity-Social-Cloud-UIKit-iOS/main/AmityUIKit.json" ~> 2.0

Now you can install Social Plus UIKit into your project by running the following command.

$ carthage update

Cocoapods Installation

If you are using CocoaPods to integrate Social Plus UIKit into your Xcode project. First, open a terminal and run this command to create Podfile.

$ pod init

Then, add the following lines to the Podfile

source "https://github.com/AmityCo/Amity-Social-Cloud-UIKit-iOS.git"
target 'SampleApp' do
  use_frameworks!
  pod 'AmityUIKit'
end

Now you can install Social Plus UIKit into your project.

$ pod install

If problems happen during pod install step. Please try cleaning Cocoapods cache before running pod install again.

To clear the cache please go to ~/Library/Caches/Cocoapods and remove all folders.

If this doesn't work, please visit the Cocoapods Github repo for further resolutions.

Usage

After finished installing SDK. You will be able to import AmityUIKit.

import AmityUIKit

Adding required permissions

Your app may require the following permissions to work properly;

1. Camera access

2. Microphone access

3. Photo library usage access

Before submitting your application to the store, please make sure the following permissions are already granted. Here are the steps to ask for permission.

Locate the info.plist file and add:

1. NSCameraUsageDescription

2. NSMicrophoneUsageDescription

3. NSPhotoLibraryUsageDescription

Setup API key

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

After logging in Console:

1. Click Settings to expand the menu.

2. Select Security.

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

If you have trouble finding this, you can post in our community forum at community.social.plus.co so our support team can assist you.

import AmityUIKit

// in order to use AmityRegionalEndpoint enum, importing AmitySDK is required.
import AmitySDK 

AmityUIKitManager.setup(apiKey: "api-key", region: .SG)

Specify Endpoints Manually (Optional)

By default, AmityClient will connect to AmityRegion.SG. You can specify endpoints manually via AmityEndpoint struct. API endpoints for each data center are different so you need to adjust the endpoint accordingly.

let endpoint = AmityEndpoint(httpUrl: "http-endpoint",
                             rpcUrl: "rpc-endpoint",
                             mqttHost: "mqtt-host")
        
AmityUIKitManager.setup(apiKey: "api-key", endpoint: endpoint)

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

Authentication

Register device

To use any SDK feature, you must first register the current device with a userId. A device registered with an userId will be permanently tied to that userId until you explicitly unregister the device, or until the device has been inactive for more than 90 days. A device registered with a specific userId will receive all messages belonging to that user.

Additionally, an optional displayName can be provided if you wish to have this user identified in push notifications.

AmityUIKitManager.registerDevice(withUserId: "USER_ID", displayName: "Ali Connors", authToken: "AUTH_TOKEN")

Register the device for push notifications

Registering your app for push notifications will require a device token as a parameter.

Social Plus's UIKit does not manage:

• User-facing requests for push notifications and authorizations

• The creation and refreshing of push notification tokens

It's up to your app to take those steps and pass the device token.

UIKitManager.registerDeviceForPushNotification("device-token") { isSuccess, error in
   // Handle completion here
}

Unregister

If 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.

AmityUIKitManager.unregisterDevice()

Using the default theme

Social Plus UIKit uses the default theme as part of the design language.

Theme customization

With no customization, UIKit already looks good. However, if you wish to customize the theme, you can declare changes to both colors and typography.

Colors

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

Usage

To declare your own colors on iOS:

1. Create an instance from the provided class AmityTheme

2. Set the theme instance through AmityUIKitManager

// default colors
let myTheme = AmityTheme()
    
// partially overriding colors
let myTheme = AmityTheme(
    primary: UIColor.systemBlue,
    secondary: UIColor.systemOrange)

// fully overriding colors
let myTheme = AmityTheme(
    primary: UIColor.systemBlue,
    secondary: UIColor.systemOrange,
    alert: UIColor.systemRed,
    highlight: UIColor.systemBlue,
    base: UIColor.white,
    baseInverse: UIColor.black,
    messageBubble: UIColor.systemTeal,
    messageBubbleInverse: UIColor.systemRed)

AmityUIKitManager.set(theme: myTheme)

Typography

The AmityTypography is a class that manages a set of UIFont properties used in Social Plus UIKit. All fonts used in our UIKit are configured under this class.

Usage

To declare your own typography on iOS:

1. Create an instance from the provided class AmityTypography.

2. Set the typography instance through AmityUIKitManager.

// default typography
let myTypography = AmityTypography()
    
// partially overriding typography
let myTypography = AmityTypography(
    headerLine: UIFont(name: "Georgia-Bold", size: 20)!,
    title: UIFont(name: "Georgia", size: 20)!)

// fully overriding typography
let myTypography = AmityTypography(
    headerLine: UIFont(name: "Georgia-Bold", size: 20)!,
    title: UIFont(name: "Georgia", size: 20)!,
    bodyBold: UIFont.systemFont(ofSize: 16, weight: .regular),
    body: UIFont.systemFont(ofSize: 16, weight: .regular),
    captionBold: UIFont.systemFont(ofSize: 13, weight: .regular),
    caption: UIFont.systemFont(ofSize: 13, weight: .light))

AmityUIKitManager.set(typography: myTypography)

Usage

Create a view controller

let viewController = AmityCommunityHomePageViewController.make()

// push
navigationController?.pushViewController(viewController, animated: true)

// present
let navigationController = UINavigationController(rootViewController: viewController)
present(navigationController, animated: true, completion: nil)

Component Customization Limitation

Social Plus UIKit provides already built UI elements on a single page. You can change the appearance such as color and typography, in the global settings. 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.

Components

• Explore

• New feed

Usage:

Create a view controller

let viewController = AmityCommunityHomePageViewController.make()

Components

• My Community

• Global feed

Usage

Create a view controller

let viewController = AmityNewsfeedViewController.make()

Features

Usage

You can use either of these two methods:

1. make - the posts will be ranked in chronological order. Below is the sample code.

   Copy

   let viewController = AmityGlobalFeedViewController.make()

2. makeCustomPostRanking - the posts will be ranked according to a score-sorting mechanism. Refer to Custom Post Ranking for more information about this feature. You can retrieve your global feed sorted by ranking score with this code.

   Copy

   let viewController = AmityGlobalFeedViewController.makeCustomPostRanking()

Features

Usage

Create a view controller

let viewController = AmityMyCommunityPreviewViewController.make()

Components

• Recommended Community

• Top trending

• Categories

Usage

Create a view controller

let viewController = AmityCommunityExplorerViewController.make()

Features

Usage

Create a view controller

let viewController = AmityRecommendedCommunityViewController.make()

Features

Usage

Create a view controller

let viewController = AmityTrendingCommunityViewController.make()

Features

Usage

Create a view controller

let viewController = AmityCategoryListViewController.make()

Features

Usage

let viewController = AmityMyCommunityViewController.make()

Features

Usage

Create a view controller

let viewController = AmityCategoryListViewController.make()

Features

Usage

Create a view controller

let viewController = EkoCategoryCommunityListViewController.make(categoryId: "CATEGORY_ID")

Feature and Component

Usage

Create a view controller

// Create type
let viewController = AmityCommunityCreatorViewController.make()

// Edit type
let viewController = AmityCommunityEditorViewController.make(withCommunityId: "COMMUNITY_ID")

Features

Usage

Create a view controller

let viewController = AmityUserProfileEditorViewController.make()

Features

Features

Features

Features

Text only

Text and Images

Device Camera

Device Image Gallery

Text and Files

Text and Videos

Polls

You can create a poll post and other users can interact with that poll post by selecting from the poll options.

Live Stream

To create a live stream post and for a detailed discussion on the live stream features, refer to Livestream Post documentation.

Features

Supported types

• File: All file types are supported

• Image: JPG, JPEG, and PNG

• Video: 3GP, AVI, FLV, MP4 and MPEG-2

Usage

Create a view controller

// Post to user feed
let viewController = AmityPostCreatorViewController.make(postTarget: .myFeed)

// Post to community feed
let viewController = AmityPostCreatorViewController.make(postTarget: .community(object: postModel))

// Poll post
let viewController = AmityPollCreatorViewController.make(postTarget: <your post target>)
self.present(viewController, animated: true, completion: nil)

Parameter

Attachment options

By default AmityPostCreatorViewController allows all attachments when creating a post. You can optionally choose attachment options when creating the post.

All available attachment options are image, video, and file. These can be found in AmityPostAttachmentType.

// Only allow file attachment in post creator page.
let settings = AmityPostEditorSettings()
settings.allowPostAttachments = [.file]
let postCreator = AmityPostCreatorViewController.make(postTarget: postTarget, settings: settings)

Social Plus 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 feature in detail. Refer to our Livestream documentation to enable livestream functionalities.

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

To create a livestream post, follow these steps:

1. Create a livestream post by selecting Livestream from the pop-up and selecting a location where you want to post the stream.

   

2. Provide a title and description for your livestream. The Go live button will not enable if you don't provide a title and description.

   

3. Add a cover thumbnail from your media gallery for the livestream post and preview the cover image. This step however is optional. You may also update and delete the cover thumbnail.

   

   

   Note: A default cover will be used if no cover thumbnail is selected.

   

4. Tap Go live to start streaming.

   

5. There will be a time indicator on the upper left. It will indicate how long it has been since the livestream started.

   

6. The livestream post will then show in the feed.

   

7. Tap Finish to end livestreaming. It will then show Ending livestream once the livestream has ended.

   

   Note: You have the option to edit or delete the livestream post from the feed.

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.

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 an 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.

Permissions

If it's your first time creating a livestream, your device will prompt to allow access to your device's camera and microphone.

You need to allow access to be able to start a livestream. The pop-up below will not show once you allow access to your camera and microphone.

Features

How to use

Create a view controller

let viewController = AmityPostDetailViewController.make(withPostId: "POST_ID")

Link Preview in Post

The Link Preview feature in posts is designed to enrich user experience by providing a visual and informative preview of external links. This feature enhances content sharing, making it more interactive and engaging. This feature significantly improves the user's posting experience. It allows for a preliminary check of the link's accuracy and relevance, adding visual appeal to the post with an informative preview.

When a user includes a link in a post, the feature automatically extracts and displays key information: the title, main image, and a short description, creating an informative preview of the linked content. If the link is unavailable, it will show a empty placeholder or error view instead.

Editing Capability

Users can edit the link preview even after the post is created. This flexibility ensures that the information remains up-to-date and accurate, enhancing the overall quality of the post.

Limitations and Use Cases:

The preview feature is designed to only display images, titles, and descriptions after a post is created. This ensures clarity and relevance in the shared content.

Features

Usage

Create a view controller

let viewController = AmityPostEditorViewController.make(withPostId: "POST_ID")

Parameter

Features

Usage

Create a view controller

let editCommentViewController = AmityCommentCreatorViewController.make(comment: AmityCommentModel, communityId: String?)

The function will create a new instance of AmityCommentCreatorViewController.

Parameters

Features

Usage

Create a view controller

let editCommentViewController = AmityCommentEditorViewController.make(comment: AmityCommentModel, communityId: String?)

The function will create a new instance of AmityCommentEditorViewController.

Parameters

Non-member View

Community Member View

Community Creator View

Components

• Community feed

• Media Gallery

Features

Usage

Create a view controller

let viewController = AmityCommunityProfilePageViewController
.make(withCommunityId: "COMMUNITY_ID")

Features

Usage

let viewController = AmityCommunityFeedViewController.make(communityId: "COMMUNITY_ID")

Features

Features

Usage

let viewController = AmityCommunityMemberSettingsViewController.make(community: community)
navigationController?.pushViewController(viewController, animated: true)

There are 2 states of User profile page:

1. User's own profile

2. Other User's Profile

Components

• User feed

Features

Usage

let viewController = AmityUserProfilePageViewController.make(withUserId: "USER_ID")

Features

Usage

// Current user feed
let viewController = AmityMyFeedViewController.make()

// Some user feed
let viewController = AmityUserFeedViewController.makeUserFeed(withUserId: "USER_ID")

There are two views for the user profile page.

1. User's own profile

This view allows the user to see his own user profile detail and his own user feed, there are two state user can see.

Default state : Allows user to see his own following user counter and Follower user counter.

Request pending state : Allows user to see his own following user counter, Follower user counter, and also the follow request he received.

Components

• User feed (2.2)

You can get this view by using this code:

let userProfileViewController = AmityUserProfilePageViewController.make(withUserId: "userId")

2. Other user's profile

This view allows the user to see other user's profile detail and their user feed. There are two states user can see

In the other user view , UIKIT has two main views that support the Follow user connection and the User privacy view.

Default state : Allows user to see the connection between the current user and the target user profile.

If the current user is NOT connected to the viewing user and Private setting is Public

If the current user is connected to the viewing user and Private setting is Public

If the current user is NOT connected to the viewing user and Private setting is Private

If the current user has send request to the viewing user and Private setting is Private

Components

• User feed (2.2)

You can get this view by using this code:

let userProfileViewController = AmityUserProfilePageViewController.make(withUserId: "userId")

Default User Feed

This view allows user to view and interact with the feed content normally. This also 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 exist if the Private setting is Private.

Features

Usage

// Current user feed
let viewController = AmityMyFeedViewController.make()

// Some user feed
let viewController = AmityUserFeedViewController.makeUserFeed(withUserId: "USER_ID")

User's Own Profile Setting Page

Other User's profile setting page

There are two main state based on the user connection.

If user is already connected with the target user

If user is not connected with the target user

You can try this code:

let userSettingsViewController = AmityUserSettingsViewController.make(withUserId: "userId")

`

Features

Usage

let viewController = AmityUserProfileEditorViewController.make()

In this page , user will see the list of the following user (users who the target userId has been following) and the follower user(users who follow the target userId).

Features

You can try it with this code:

let vc = AmityUserFollowersViewController.make(withUserId: "userId")
navigationController?.pushViewController(vc, animated: true)

In this page, user can see all the follow request he has received. He can either accept or decline the request as well.

You can use the component with this code:

let requestsViewController = AmityFollowRequestsViewController.make(withUserId: "userId")
navigationController?.pushViewController(requestsViewController, animated: true)

Features

Usage

let vwiewController = AmityMemberPickerViewController.make()
navigationController?.pushViewController(viewController, animated: true)

Features

Usage

let viewController = AmityPostTargetPickerViewController.make()

Social Plus UIKit allows some parts of the component to be customized:

• Using your own navigation bar

Usage

let communityHomePage = AmityCommunityHomePageViewController.make()
communityHomePage.navigationBarType = .custom

// create custom view
let label = UILabel()
label.text = "This is a navigation custom view"
label.backgroundColor = .orange

// assign custom view to title view
homepage.navigationItem.titleView = label

UIKIT allows the default behaviour to be overridden by custom logic.

• Post Sharing

• Post Rendering

Post Sharing Settings

This setting allows you to control where a post can be shared to based on the post origin.

There are five possible targets that a post can be shared to

My feed - The post can be shared to my feed. This option will enable "Share to my timeline" menu when user clicks share button.

Public community - The post can be shared to any public community. This option will enable "Share to group" menu when user clicks share button.

Private community - The post can be shared to any private community. This option will enable "Share to group" menu when user clicks share button.

External - The post can be shared externally. This option will enable "More options" menu when user clicks share button.

Origin - The post can be shared within the community feed that it was created. If the post was created in either public or private community, this option will enable "Share to group" menu when user clicks share button.

There are four possible origins

My feed post - Posts that were created on my feed. By default, possible sharing targets are My feed, Public community, and Private community.

User feed post - Posts that were created on any other users' feed. By default, possible sharing targets are My feed, Public community, and Private community.

Public community feed post - Posts that were created on any public community. By default, possible sharing targets are My feed, Public community, and Private community.

Private community feed post - Posts that were created on any private community. By default, possible sharing target is Origin.

Usage

You can select a set of targets for each post origin.

// In your AppDelegate class

// Ensure post created in private community cannot be shared elsewhere
let privateCommunityShringTargets: Set<AmityPostSharingTarget> = [.originFeed]

// Allow post created by any other user to be shared anywhere
let publicCommunityShringTargets: Set<AmityPostSharingTarget> = [.myFeed, .originFeed, .publicCommunity, .external]

// Allow post created by logged-in user to be shared anywhere
let myFeedShringTargets: Set<AmityPostSharingTarget> = [.myFeed, .originFeed, .external]
        
let sharingSettings = AmityPostSharingSettings(privateCommunity: privateCommunityShringTargets, publicCommunity: publicCommunityShringTargets, myFeed: myFeedShringTargets)
        
AmityUIKitManager.feedUISettings.setPostSharingSettings(settings: sharingSettings)

Post Sharing Events

Based on Post sharing settings, there are up to three post sharing events that can be emitted by UIKit.

Share to my timeline - an event emitted when a user clicks on "Share to my timeline" button.

Share to group - an event emitted when a user clicks on "Share to group" button.

Share externally - an event emitted when a user clicks "More options" button.

Usage

You can choose to intercept one or all of the events and apply your custom behavior.

// In your AppDelegate class

// Create custom event handler class
class CustomFeedEventHandler: AmityFeedEventHandler {
    // Event handler for more options
    override func sharePostDidTap(from source: AmityViewController, postId: String) {
        // generate a link 
        let urlString = "https://amity.co/posts/\(postId)"
        guard let url = URL(string: urlString) else { return }
        
        // create AmityActivityController to share generated link
        let viewController = AmityActivityController.make(activityItems: [url])
        source.present(viewController, animated: true, completion: nil)
    }
    
    // Event handler for share post to group
    override func sharePostToGroupDidTap(from source: AmityViewController, postId: String) {
        // Handle event here
    }
    
    // Event handler for share to my timeline
    override func sharePostToMyTimelineDidTap(from source: AmityViewController, postId: String) {
        // Handle event here
    }
}

...

AmityUIKitManager.feedUISettings.eventHandler = CustomFeedEventHandler()

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 UITableViewCell. This allows reusability of cell components such as header or footer which can be shared by different kinds of posts.

This is an example of simple text post which contains 3 tableview cell. Top cell represents the header, middle cell contains text content and bottom cell is footer cell.

Creating UI for custom posts :

There are 3 steps involved in creating custom post renderer.

Step 1: Create your UI using UITableView cells.

class MyPostHeaderCell: UITableViewCell { 
    // ...
}

class MyPostContentCell: UITableViewCell {
    // ...
}

Step 2: Compose a post UI component. For this create a component which conforms to AmityPostComposable protocol.

struct MyCustomPostComponent: AmityPostComposable {
    
    var post: AmityPostModel
    
    // Post data model which you can use to render ui.
    init(post: AmityPostModel) {
        self.post = post
    }
    
    func getComponentCount(for index: Int) -> Int {
        return 2
    }
    
    func getComponentCell(_ tableView: UITableView, at indexPath: IndexPath) -> UITableViewCell {
        switch indexPath.row {
        case 0:
            let cell = tableView.dequeueReusableCell(withIdentifier: "my-cell-identifier", for: indexPath) as! MyPostHeaderCell
            // ... populate cell data here
            return cell
        case 1:
            let cell = tableView.dequeueReusableCell(withIdentifier: "my-cell-identifier", for: indexPath) as! MyPostContentCell
            // ... populate cell data here
            return cell
        default:
						fatalError("indexPath is out of bound")
        }
    }
    
    // Height for each cell component
    func getComponentHeight(indexPath: IndexPath) -> CGFloat {
        return UITableView.automaticDimension
    }
}

You can also use our default header cell AmityPostHeaderTableViewCell & default footer cell AmityPostFooterTableViewCell in your custom post component.

Step 3: Register your custom cell & implement datasource.

class YourViewController: UIViewController {
    
		func showFeed() {
				// 1.
				// Register your cell here. You can register both 
				// nib as well as class itself.
				AmityFeedUISettings.shared.register(UINib(nibName: "PostThumbsupTableViewCell", bundle: nil), forCellReuseIdentifier: "PostThumbsupTableViewCell")
        AmityFeedUISettings.shared.dataSource = self

        // Showing our feed UI
				let feedViewController = AmityGlobalFeedViewController.make()
	      navigationController?.pushViewController(feedViewController, animated: true)
		}
}

extension YourViewController: AmityFeedDataSource {
    
    // 2. 
    // Provide your rendering component for custom post.
    func getUIComponentForPost(post: AmityPostModel, at index: Int) -> AmityPostComposable? {
        switch post.dataType {
        case "your-data-type":
            return MyCustomPostComponent(post: post)
        default:
            return nil
        }
    }
}

Custom Event Handler

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

Supported Events

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

To customize message cell layouts, please follow these instructions:

1. Create a subclass of UITableViewCell and conform it to AmityMessageCellProtocol

2. To bind message data to UI, implement display(message:). You can also implement height(for message:boundingWidth:) to specify the cell height. We've included some examples below for static-height calculation and dynamic-height calculation as reference

3. Subclass AmityEventHandler, and override its default functions channelDidTap(from:channelId:) and conform to AmityMessageListDataSource.

class CustomChannelEventHandler: AmityChannelEventHandler {
    
    override func channelDidTap(from source: AmityViewController, channelId: String) {
        let viewController = AmityMessageListViewController.make(channelId: channelId, settings: settings)
        viewController.dataSource = self
        source.navigationController?.pushViewController(viewController, animated: true)
    }
    
}

extension CustomChannelEventHandler: AmityMessageListDataSource {
    func cellForMessageTypes() -> [AmityMessageTypes : AmityMessageCellProtocol.Type] {
	// determine which cell represents for which message type.
        return [
            .imageIncoming: StaticHeightMessageCell.self,
	.textIncoming: DynamicHeightMessageCell.self
        ]
    }
}

4. Assign a class instance through a set function of AmityUIKitManager

AmityUIKitManager.set(channelEventHandler: CustomChannelEventHandler())

Customizing Cells with Different Layouts

Static-Height Cell Layout

You can use static-height cell layout types for static content, where the cell height is fixed and will not be scaled regardless of the data being received.

Below is an example of how you can configure a static-height cell layout. In this example, we're assuming that the image message is a class named StaticHeightMessageCell.

class StaticHeightMessageCell: UITableViewCell, AmityMessageCellProtocol {
    
    func display(message: AmityMessageModel) {
        // configure cell here, e.g. set message text to label.
    }
    
    static func height(for message: AmityMessageModel, boundingWidth: CGFloat) -> CGFloat {
        // Calculate the actualHeight by summing up all components height.
        let actualHeight: CGFloat = 34 + 228 + 34 // 296
        
        return actualHeight
    }
    
}

Dynamic-Height Cell Layout

You can use dynamic-height cell layout when you require your cell height to expand dynamically according to the data (e.g. label expands upon strings).

Dynamic-height cell layouts require more complexity in height calculation. Let's look at a text message as an example, where the height of the cell needs to expand dynamically to display the full content.

class DynamicHeightMessageCell: UITableViewCell, AmityMessageCellProtocol {
    
    func display(message: AmityMessageModel) {
        // configure cell here, e.g. set message text to label.
    }
    
    static func height(for message: AmityMessageModel, boundingWidth: CGFloat) -> CGFloat {
        
        // (1) Calculate the width that is reserved by other components.
        let reservedWidth: CGFloat = 12 + 40 + 12 + 8 + 8 + 76 // 156
        
        // (2) Calculate the maximum possible width that content can fit in.
        //
        // A `boundingWidth` is a width that returns from table view. In this example is 375.
        // To get the possible with. We need to subtract it by (1).
        let possibleWith: CGFloat = boundingWidth - reservedWidth // 375 - 156 = 210
        
        // (3) Calculate the content height using font and string.
        let messageHeight = message.text?.height(withConstrainedWidth: possibleWith, font: AmityFontSet.body) ?? 0.0
        
        // (4) Calculate the height that is reserved by other component.
        let reservedHeight: CGFloat = 34 + 8 + 8 + 34 // 84
        
        // (5) Calculate the actualHeight by summing up (3) and (4).
        let actualHeight: CGFloat = messageHeight + reservedHeight
        
        return actualHeight
    }
    
}

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

Moderator badge

The "Moderator" badge shown on the post and the comment indicates it was created by a moderator user.

With our chat functionality in Social Plus UIKit, you can explore how best to integrate and design messaging features and how they will look in your app.

Usage

import UIKit
import AmityUIKit

class ClientViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func showChatListPage(_ sender: UIButton) {
        let chatHomeVC = AmityChatHomePageViewController.make()
        present(chatHomeVC, animated: true)
    }
}

Limitation

UIKit provides already built UI elements in one page. You can change the appearances, such as color and typography in the global settings. However, UIKit does not allow you to replace these small components with other views. And you cannot modify the view hierarchy inside the page.

Components

• Recent chat

Usage

import UIKit
import AmityUIKit

class ClientViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func showChatListPage(_ sender: UIButton) {
        let chatHomePageVC = AmityChatHomePageViewController.make()
        present(chatHomePageVC, animated: true)
    }
}

Features

Usage

import UIKit
import AmityUIKit

class ClientViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func showChatListPage(_ sender: UIButton) {
        let recentChatVC = AmityRecentChatViewController.make()
        present(recentChatVC, animated: true)
    }
}

Message List Page Header

Message List

Message Bubble - Text Message Bubble

Message bubble - Image message bubble

Image Preview Page

Message Bubble - Audio Message Bubble

Audio Message Recorder

Edit Text Message Page

Usage

import UIKit
import AmityUIKit

class ClientViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func showMessageListPage(_ sender: UIButton) {
        let messageVC = AmityMessageListViewController.make(channelId: "CHANNEL_ID")
        present(messageVC, animated: true)
    }
}

Parameters

Specify Custom Settings

You can create and specify Settings object when creating AmityMessageListViewController.

// 1. Create the settings object.
var settings = AmityMessageListViewController.Settings()
settings.composeBarStyle = .textOnly

// 2. Specify the settings as parameter.
let messageVC = AmityMessageListViewController.make(channelId: "CHANNEL_ID", settings: settings)

The available settings are shown below.

Compose Bar Style

There are two compose bar styles available in the UIKit.

1. ComposeBarStyle.default - has full functionalities including text, audio and, image message sending

2. ComposeBarStyle.textOnly - has simple functionalities which are only limited to text message sending

The default settings for compose bar style is ComposeBarStyle.default.

Social Plus UIKit allows you to personalise some parts of the component.

Text Message Bubble

Image Massage Bubble

Audio Message Bubble

Usage

To customize message UI, create a new UITableViewCell and conform to AmityMessageCellProtocol.

import UIKit
import AmityUIKit

class CustomTableViewCell: UITableViewCell, AmityMessageCellProtocol {
    func display(message: AmityMessageModel) {
        // Do stuff
    }
}

import UIKit
import AmityUIKit

class ClientViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func showChatPage(_ sender: UIButton) {
        let chatVC = AmityChatHomePageViewController.make()
        chatVC.messageDataSource = self
        present(recentChatVC, animated: true)
    }
}

extension ClientViewController: AmityMessageListDataSource {
    func cellForMessageTypes() -> [AmityMessageTypes: AmityMessageCellProtocol.Type] {
        return [.textIncoming: CustomTableViewCell.self]
    }
}

More than ever, videos are increasingly dominating mobile screens. From fun short-form clips to promote new products to live-streamed talk shows to educate your customers, videos have the potential to transform the way customers experience your brand.

The UIKit now supports live stream posts so you can create and watch live streams.

Installation

To enable live stream functionalities easily, we’ve provided AmityUIKitLiveStream, which is built on top of Social Plus UIKit and Social Plus SDK.

The plugin provides:

• LiveStreamBroadcastViewController to create and broadcast live stream posts

• LiveStreamPlayerViewController to watch live streams

The live stream plugin can be installed via Swift Package Manager with these steps:

1. In Xcode, select File > Swift Packages > Add Package Dependency.

2. Specify the Repository: https://github.com/AmityCo/Amity-Social-Cloud-UIKit-LiveStream-iOS-SwiftPM.

3. Select Up to Next Major, then click Next.

4. Select AmityUIKitLiveStream, then click Finish.

After successfully installing the plugin, you must override the live stream behaviors with these steps:

1. Create AmityEventHandler subclass, and override live stream functions.

   Copy

   import UIKit
   import AVKit
   import AmityUIKit
   import AmitySDK
   import AmityUIKitLiveStream
   import AmityVideoPlayerKit
   
   class CustomEventHandler: AmityEventHandler {
       
       override func createLiveStreamPost(
           from source: AmityViewController,
           targetId: String?,
           targetType: AmityPostTargetType,
           destinationToUnwindBackAfterFinish: UIViewController
       ) {
           
           let broadcastVC =
               LiveStreamBroadcastViewController(client: AmityUIKitManager.client, targetId: targetId, targetType: targetType)
           broadcastVC.destinationToUnwindBackAfterFinish = destinationToUnwindBackAfterFinish
           broadcastVC.modalPresentationStyle = .fullScreen
           source.present(broadcastVC, animated: true, completion: nil)
           
       }
       
       override func openLiveStreamPlayer(from source: AmityViewController, postId: String, streamId: String) {
           
           let playerVC = LiveStreamPlayerViewController(streamIdToWatch: streamId)
           source.present(playerVC, animated: true, completion: nil)
           
       }
       
       override func openRecordedLiveStreamPlayer(from source: AmityViewController, postId: String, stream: AmityStream) {
           let player = AmityRecordedStreamPlayer(client: AmityUIKitManager.client, stream: stream)
           let playerViewController = AVPlayerViewController()
           playerViewController.player = player
           source.present(playerViewController, animated: true) { [weak player] in
               player?.play()
           }
       }
       
   }

2. Set the custom event handler for Social Plus UIKit.

   Copy

   AmityUIKitManager.set(eventHandler: CustomEventHandler())

App Permissions

LiveStreamBroadcastViewController requires these permissions:

1. Camera Permission - to broadcast live stream video

2. Microphone Permission - to broadcast live stream audio

After LiveStreamBroadcastViewController is presented, it will prompt to ask permission automatically if needed. You must include these permission keys in your app’s Info.plist file:

1. NSCameraUsageDescription

2. NSMicrophoneUsageDescription

Introduction

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

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

To customize Social Plus 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 Social Plus UIKit open source when:

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

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

Please note that we will extend only 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 Social Plus UIKit open-source wiki for any documentation related to Social Plus UIKit open-source.

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

Community Guidelines

If you would like to suggest improvements to 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 Social Plus UIKit open-source wiki or you may go directly to these related pages:

• Customizing Social Plus UIKit Open Source

• Contributing to Social Plus UIKit Open Source

• Submitting fixes and feature requests

Benefits

• Easy Installation.

• Fully-featured chat experience with minimal coding.

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

Requirements

• Android 5.0 (API level 21 or higher)

• Java 8

• AndroidX

• Material components

• Gradle 3.4.0 or higher

Implementation Strategies

The UIKit API provides several strategies to integrate with your application.

Page Presentation

• Use the UIKit, ready to use out of the box

• Integrate the Chat experience in the least amount of effort.

Page Presentation (Custom)

• Add a custom theme to the default implementation of the UIKit.

• Complete control of the visual style of Chat UI by implementing declarative styles (fonts and colors) for your user interface.

Page Integration

• Use key components from the UIKit SDK and integrate them directly into your application.

• Add the Chat UI to your existing design.

Key Concepts

Architecture

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

In the current state, there are two modules that can be used. You can follow the steps below. These two modules can be integrated into your application with ease using this documentation.

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 Android 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 Android Open Source UI Kit with Existing Project

Remove existing gradle dependency

If you've never used UI Kit from a gradle dependency before, you may skip this step and proceed to the next step. If you are migrating the UIKit with an existing gradle dependency, you will need to remove it from the gradle at the application level.

implementation 'com.github.AmityCo.Amity-Social-Cloud-UIKit-Android:amity-uikit:x.y.z'

Import UI Kit module to your existing project

• Clone or download source code from an open-source Github repository. https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android-OpenSource

• Navigate to your current application in Android Studio, then at the top navigation bar go to File > New > Import Module...

• Choose the source directory where you downloaded/cloned UI Kit source code.

• Make sure that you import :chat , :common, :social, and :amity-uikit module as per the screenshot described. The :sample module is optional and solely contains examples of UIKit Fragments and Activities.

• Navigate to the root project's settings.gradle file once the modules have been successfully imported. You may see that Android Studio generated a dependency path from the UI Kit source code directory you specified initially. However, there's a chance that Android Studio won't do so or may generate the incorrect path. Please double-check that the path is accurate.

• Additionally, in the root project's settings.gradle it's also mandatory to declare jitpack.io repository destination by adding maven { url https://jitpack.io } to dependencyResolutionManagement > repositories.

• Add the imported module to application's gradle file by adding:

implementation project(path: ':amity-uikit')

• Exclude these META-INF from the packaging options in application's gradle

 packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }

• Lastly, apply this in the project-level build.gradle file. apply from: "../Amity-Social-Cloud-UIKit-Android/buildsystem/dependencies.gradle"

Woohoo! All set now you're ready to explore and modify our UI Kit in your application project.

Modifying Android Open Source UI Kit

You can modify the Android 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 Open Source UI Kit Updates

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

cd Amity-Social-Cloud-UIKit-Android-OpenSource
git pull origin master
cd ..
git add .
git commit -m “Update android uikit opensource submodule”
git push origin branch_name

Prerequisite

SDK supports Android 5.0 (API Level 21) and above

android {
    ...
    defaultConfig {
        minSDKVersion 21 // at least 21
    }
}

Installation

Add the Jitpack repository in your project level build.grade at the end of repositories:

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

Add the dependency in your module level build.grade. Find latest UIKit version at Changelog.

// add buildFeatures, compileOptions and kotlinOptions in android tag
android {

    buildFeatures {
        dataBinding = true
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }
    
}
    
dependency {
implementation 'com.github.AmityCo.Amity-Social-Cloud-UIKit-Android:amity-uikit:x.y.z'
}

Managing Conflicting File Generation

In your app module's build.gradle , add the following packaging options.

android {
    ...
    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}

Code Obfuscation

By using our SDK, you can use the Android ProGuard tool to obfuscate, shrink, and optimize your code. Obfuscated code can be more difficult for other people to reverse engineer. ProGuard renames classes, fields, and methods with semantically obscure names and removes unused code. However, you need to add these configurations to your ProGuard rules when using our SDK.

-keep class com.ekoapp.ekosdk.** { *; }
-keep interface com.ekoapp.ekosdk.** { *; }
-keep enum com.ekoapp.ekosdk.** { *; }
-keep class com.amity.socialcloud.** { *; }
-keep interface com.amity.socialcloud.** { *; }
-keep enum com.amity.socialcloud.** { *; }

Compatibility

We are always working to enhance our existing UIKit. As a result, the minimum compatibility may vary for our previous version releases. Below is the compatibility list for our latest release. For a complete compatibility history of any given UIKit version, you may refer to our changelogs.

• Glide - 4.12.0

• OKHTTP3 - 4.9.02

• Retrofit2 - 2.9.1

• Android Paging Data Library - 3.1.1

• Room - 2.5.1

• RxJava3 - 3.1.5

• Gson - 2.8.10

• Kotlin-std-lib - 1.7.20

• Kotlin-coroutines - 1.5.0

• Media 3 - 1.1.0

• HiveMQ mqtt client - 1.3.1

Initialize the SDK

Before using the SDK, you need to initialize the SDK with your API key. Please find your account API key in Social Plus Cloud Console.

After logging in Console:

1. Click Settings to expand the menu.

2. Select Security.

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

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:

Authentication

You must first register the current device with a userId. A device registered with a userId will be permanently tied to that userId until you deliberately unregister the device, or until the device has been inactive for more than 90 days. A device registered with a specific userId will receive all messages belonging to that user.

Using the default theme

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

Theme customization

The UIKit looks great without any customizations, though you can also edit the colors and fronts in the themes to suit your preferences all the same. However, if you wish to customize the theme, you can declare changes to both colors and typography.

Colors

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

Usage

Customize color theme by declaring color code to the specific color key.

colors.xml

<resources>
    <color name="amityColorPrimary">#1054DE</color>
    <color name="amityColorSecondary">#292B32</color>
    <color name="amityColorAlert">#FA4D30</color>
    <color name="amityColorHighlight">#1054DE</color>
    <color name="amityColorBase">#292B32</color>
    <color name="amityColorBaseInverse">#FFFFFF</color>
    <color name="amityMessageBubble">#1054DE</color>
    <color name="amityMessageBubbleInverse">#EBECEF</color>
</resources>

Overriding the default UIKit theme

When you integrate UIKit to your application, it applies the our customized theme to UIKit by default. This Amity.Base.Theme.AmityApp style extends a theme from our material based theme and includes overrides for styling attributes that are used by key UI elements. So you can quickly customize UIkit style by overriding the provided theme file and its attributes. Please note that all following attributes must be overriden.

For example, your styles.xml file should look similar to this:

    <!--     Override Amity UIKIT Theme, all of these attributes are mandatory. You could override them , but please don't remove any. Otherwise ui theme may be strange-->
    <style name="Amity.Base.Theme.AmityApp" parent="Amity.Base.Theme.MaterialThemeBuilder">
        <!--        Color of status bar-->
        <item name="android:statusBarColor">#000000</item>
        <!--        Light/dark theme of status bar-->
        <item name="android:windowLightStatusBar" tools:targetApi="23">false</item>
        <!--        Navigation bar color-->
        <item name="android:navigationBarColor">#000000</item>
        <!--        Global toolbar style-->
        <item name="toolbarStyle">@style/MyToolbarStyle</item>

        <!--        Primary accent color-->
        <item name="colorPrimary">@color/amityColorPrimary</item>
        <!--        Secondary accent color-->
        <item name="colorSecondary">@color/amityColorSecondary</item>
        <!--        Global background color-->
        <item name="android:colorBackground">@color/amityColorWhite</item>
        <item name="colorSurface">@color/amityColorWhite</item>

        <item name="colorError">@color/amityColorAlert</item>
        <item name="colorOnError">@color/amityColorWhite</item>
        <item name="android:actionMenuTextColor">@color/amityColorHighlight</item>

        <item name="materialAlertDialogTheme">@style/AmityAlertDialogTheme</item>
        <!--        Snackbar style-->
        <item name="snackbarStyle">@style/AmitySnackBarStyle</item>
        <!--        Search view style-->
        <item name="searchViewStyle">@style/AmitySearchViewStyle</item>

        <item name="shapeAppearanceSmallComponent">@style/Amity.ShapeAppearance.Theme.SmallComponent
        </item>
        <item name="shapeAppearanceMediumComponent">
            @style/Amity.ShapeAppearance.Theme.MediumComponent
        </item>
        <item name="shapeAppearanceLargeComponent">@style/Amity.ShapeAppearance.Theme.LargeComponent
        </item>
        <item name="bottomSheetDialogTheme">@style/Amity.ThemeOverlay.Theme.BottomSheetDialog</item>
    </style>

    <!--       Example of custom toolbar style, color is the only option can be customised here-->
    <style name="MyToolbarStyle" parent="Widget.MaterialComponents.Toolbar">
        <!--       Color of toolbar-->
        <item name="android:background">#3A3A3A</item>
    </style>

    <!--     Override Amity UIKIT text style in toolbar, all of these attributes are mandatory.
              You could override them but please don't remove any. Otherwise ui theme may be strange-->
    <style name="ToolBarLeftTextStyle">
        <!--     Please don't change width and height-->
        <item name="android:layout_width">0dp</item>
        <item name="android:layout_height">wrap_content</item>
        <!--     Text size of the toolbar title text-->
        <item name="android:textSize">@dimen/amity_text_size_title</item>
        <!--     Style of the toolbar title text-->
        <item name="android:textStyle">bold</item>
        <!--     Margin of the toolbar title text-->
        <item name="android:layout_marginStart">@dimen/amity_padding_m1</item>
        <!--     Text color of the toolbar title text-->
        <item name="android:textColor">#FFFF</item>
        <item name="android:maxLines">1</item>
        <item name="android:ellipsize">end</item>
        <item name="android:layout_marginEnd">@dimen/amity_padding_m1</item>
    </style>

    <!--     Override Amity UIKIT left icon in toolbar, all of these attributes are mandatory.
          You could override them but please don't remove any. Otherwise ui theme may be strange-->
    <style name="ToolBarLeftDrawableStyle">
        <!--     Please don't change width and height-->
        <item name="android:layout_width">wrap_content</item>
        <item name="android:layout_height">wrap_content</item>
        <!--     Color of the toolbar icon-->
        <item name="android:tint">#FFFF</item>
        <item name="android:layout_marginStart">@dimen/amity_padding_m2</item>
    </style>

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

Usage

Start an Activity

val intent = Intent(this, AmityCommunityHomePageActivity::class.java)
startActivity(intent)

Create a Fragment

class MyCommunityHomeActivity: AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_my_community_home)
        if(savedInstanceState == null) {
            val fragmentManager = supportFragmentManager
            val fragmentTransaction = fragmentManager.beginTransaction()
            val fragment = createCommunityHomeFragment()
            fragmentTransaction.replace(R.id.fragmentContainer, fragment)
            fragmentTransaction.commit()
        }
    }

    private fun createCommunityHomeFragment(): Fragment {
        return AmityCommunityHomePageFragment.Builder().build(activity)
    }
}

Limitation

UIKit provides already built UI elements in one page. You can change the appearances, such as color and typography in the global settings. However, UIKit does not allow you to replace these small components with other views. And you cannot modify the view hierarchy inside the page.

Components

• Explore

• Newsfeed

Usage

Create a Fragment

AmityCommunityHomePageFragment
           .newInstance()
           .build()

Components

• My Community

• Global feed

Usage

Create a Fragment

AmityNewsFeedFragment.newInstance().build()

Features

Usage

Create a Fragment

You can use either of these two methods:

1. build - the posts will be ranked in chronological order. Below is the sample code.

   Copy

   AmityGlobalFeedFragment.newInstance().build()

2. <newCustomPostRankingmethod> - the posts will be ranked according to a score-sorting mechanism. Refer to Custom Post Ranking for more information about this feature. You can retrieve your global feed sorted by ranking score with this code.

   Copy

   let viewController = AmityGlobalFeedViewController.makeCustomPostRanking()

Features

Usage

Create a Fragment

AmityMyCommunityPreviewFragment.newInstance().build()

Components

• Recommended Community

• Top trending

• Categories

Usage

Create a Fragment

AmityExploreFragment.newInstance().build()

Features

Usage

Create a Fragment

AmityRecommendedCommunityFragment.newInstance().build()

Features

Usage

Create a Fragment

AmityTrendingCommunityFragment.newInstance().build()

Features

Usage

Create a Fragment

AmityCategoryPreviewFragment.newInstance().build()

Features

Usage

AmityMyCommunityFragment
    .newInstance()
    .enableSearch(true) // seach view to search community
    .showOptionsMenu(true) // option menu to create community in toolbar
    .build()

Features

Usage

Start an Activity

val intent = Intent(this, AmityCategoryListActivity::class.java)
startActivity(intent)

Create a Fragment

AmityCategoryListFragment.newInstance().build(activity)

Features

Usage

Start an Activity

val intent = AmityCategoryCommunityListActivity.newIntent( this, category)
startActivity(intent)

Create a Fragment

AmityCategoryCommunityListFragment
            .newInstance()
            .category(category)
            .build()

Feature and Component

Usage

Start an Activity

val intent =  Intent(this, AmityCommunityCreatorActivity::class.java)
startActivity(intent)

Create a Fragment

AmityCommunityCreatorFragment.newInstance().build()

Features

Usage

Create a Fragment

AmityCommunityEditorFragment
    .newInstance(community or communityId)
    .build(activity)

Types of Post Creations:

Text

Text and Images

User can select images from 2 sources.

Device Camera

Device Image Gallery

Text and Files

Text and Videos

Polls

Livestream

To create a live stream post and for a detailed discussion on the live stream features, refer to Livestream post documentation.

Features

Usage

Create a Fragment

User can create a post either on a community feed or user's own feed.

Attachment options

We currently support three types of attachment option when creating a post. These are:

1. AmityPostAttachmentItem.PHOTO

2. AmityPostAttachmentItem.VIDEO

3. AmityPostAttachmentItem.FILE .

You can optionally choose to allow these attachment options by using the method allowPostAttchments. By default the fragment includes all attachment options.

Create a post on community feed

//for text, image, file, video post
AmityPostCreatorFragment.newInstance()
    .onCommunityFeed(community or communityId)
     //optional
     .allowPostAttachments(
           listOf(
                   AmityPostAttachmentOptionItem.PHOTO,
                   AmityPostAttachmentOptionItem.VIDEO,
                   AmityPostAttachmentOptionItem.FILE
               )
           )
    .build()
    
//for poll post    
AmityPollPostCreatorFragment.newInstance()
    .onCommunityFeed(community or communityId)
    .build()

Create a post on user's own feed

//for text, image, file, video post
AmityPostCreatorFragment.newInstance()
     .onMyFeed()
     //optional
     .allowPostAttachments(
           listOf(
                   AmityPostAttachmentOptionItem.PHOTO,
                   AmityPostAttachmentOptionItem.VIDEO,
                   AmityPostAttachmentOptionItem.FILE
               )
           )
     .build()
   
//for poll post      
AmityPollPostCreatorFragment.newInstance()
     .onMyFeed()
     .build()

Our 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 recording feature in detail.

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

To create a livestream post, follow these steps:

1. Create a livestream post by selecting Livestream from the pop-up and selecting a location where you want to post the stream.

   

2. Provide a title and description for your livestream. The title and description will be blank if you will not provide any.

   

3. Add a cover thumbnail from your media gallery for the livestream post and preview the cover image. This step however is optional. You may also update and delete the cover thumbnail.

   

   

4. Tap Go live to start streaming.

   

5. There will be a time indicator on the upper left. It will indicate how long it has been since the livestream started.

   

6. The livestream post will then show in the feed.

   

7. Tap Finish to end livestreaming. It will then show Ending livestream once the livestream has ended.

   

   Note: You have the option to edit or delete the post from the feed.