Introduction

Welcome to the Amity UIKit 4.0 Beta, the latest iteration of our powerful user interface toolkit, designed to revolutionize the way you build interactive and engaging applications. This beta release marks a significant milestone in our ongoing commitment to providing robust, user-friendly, and versatile UI solutions.

The Amity UIKit 4.0 Beta proudly introduces an exclusive and highly anticipated feature: The Story Feature. This addition is a game-changer, allowing developers to integrate a dynamic and rich storytelling component into their applications effortlessly. With the Story Feature, users can create, share, and interact with content in a more engaging and visually appealing way, similar to popular social media platforms.

Future Expansion and Migration

We envision Amity UIKit 4.0 to be a continually evolving platform, introducing new features and integrating existing ones from Amity UIKit 3.x. This approach ensures a holistic and advanced UIKit. For users of UIKit 3.x, we are dedicated to providing a smooth transition to the 4.0 UIKit.

Design Alignment

In line with the introduction of Amity UIKit 4.0, we are also updating the design of the entire Amity UIKit. This update aims to align with the sleek, modern, and user-centric design philosophy of UIKit 4.0. The updated design will not only enhance the visual appeal but also improve the overall user experience, making it more intuitive, responsive, and accessible.

Unparalleled Customization

One of the core enhancements in Amity UIKit 4.0 is its unmatched customization capability. Understanding the diverse needs of developers and businesses, we have designed the UIKit to be highly adaptable. Whether it's tweaking the UI elements, adjusting the layout, or modifying the color schemes, the toolkit provides an extensive range of customization options.

Simplifying Integration

The primary goal of Amity UIKit 4.0 is to simplify the integration process. We strive to make the incorporation of our UIKit into your existing projects as seamless as possible. With comprehensive documentation, user-friendly APIs, and a supportive community, we aim to reduce the complexity and time involved in integrating advanced UI features into your applications.

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 .

• Amity-Social-Cloud-SDK - 5.14.0

• Glide - 4.12.0

• OKHTTP3 - 4.9.0

• Retrofit2 - 2.50

• Android Paging Data Library - 3.0.1

• Room - 2.4.0-alpha04

• RxJava2 - 2.3.10

• Gson - 2.8.10

• Kotlin-std-lib - 1.5.10

• Kotlin-coroutines - 1.5.0

• Exo Player - 2.12.1

• HiveMQ mqtt client - 1.2.2

Initialize the SDK

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.

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:

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.

Configuration file

Our UIKit v4 supports customization in a single place by modifying a config.json file in related UIKit repository. This configuration file includes all necessary data to customize the appearance of each pages, components and elements that we allow to do customization.

{
  "global_theme": {
    "light_theme": {
      "primary_color": "#FFFFFF",
      "secondary_color": "#AB1234"
    }
  },
  "excludes": [
  ],
  "customizations": {
    "select_target_page/*/*": {
      "page_theme": {
        "light_theme": {
          "primary_color": "#1D1234",
          "secondary_color": "#AB1234"
        }
      },
      "title": "Share to"
    },
    "select_target_page/*/back_button": {
      "back_icon": "back.png"
    },
    "camera_page/*/*": {
      "resolution": "720p",
      "page_theme": {
        "light_theme": {
          "primary_color": "#000000",
          "secondary_color": "#AB1234"
        }
      }
    },
    "camera_page/*/close_button": {
      "close_icon": "close.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/*": {},
    "create_story_page/*/back_button": {
      "back_icon": "back.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/aspect_ratio_button": {
      "aspect_ratio_icon": "aspect_ratio.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/story_hyperlink_button": {
      "hyperlink_button_icon": "hyperlink_button.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/hyper_link": {
      "hyper_link_icon": "hyper_link.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/share_story_button": {
      "share_icon": "share_story_button.png",
      "background_color": "#FFFFFF",
      "hide_avatar": false
    },
    "story_page/*/*": {},
    "story_page/*/progress_bar": {
      "progress_color": "#FFFFFF",
      "background_color": "#50FFFFFF"
    },
    "story_page/*/overflow_menu": {
      "overflow_menu_icon": "threeDot.png"
    },
    "story_page/*/close_button": {
      "close_icon": "close.png"
    },
    "story_page/*/story_impression_button": {
      "impression_icon": "impressionIcon.png"
    },
    "story_page/*/story_comment_button": {
      "comment_icon": "comment.png",
      "background_color": "#1234DD"
    },
    "story_page/*/story_reaction_button": {
      "reaction_icon": "like.png",
      "background_color": "#1243EE"
    },
    "story_page/*/create_new_story_button": {
      "create_new_story_icon": "plus.png",
      "background_color": "#1243EE"
    },
    "story_page/*/speaker_button": {
      "mute_icon": "mute.png",
      "unmute_icon": "unmute.png",
      "background_color": "#1243EE"
    },
    "*/edit_comment_component/*": {
      "component_theme": {
        "light_theme": {
          "primary_color": "#1D1234",
          "secondary_color": "#AB1234"
        }
      }
    },
    "*/edit_comment_component/cancel_button": {
      "cancel_icon": "",
      "cancel_button_text": "cancel",
      "background_color": "#1243EE"
    },
    "*/edit_comment_component/save_button": {
      "save_icon": "",
      "save_button_text": "Save",
      "background_color": "#1243EE"
    },
    "*/hyper_link_config_component/*": {
      "component_theme": {
        "light_theme": {
          "primary_color": "#1D1234",
          "secondary_color": "#AB1234"
        }
      }
    },
    "*/hyper_link_config_component/done_button": {
      "done_icon": "",
      "done_button_text": "Done",
      "background_color": "#1243EE"
    },
    "*/hyper_link_config_component/cancel_button": {
      "cancel_icon": "",
      "cancel_button_text": "Cancel"
    },
    "*/comment_tray_component/*": {
      "component_theme": {
        "light_theme": {
          "primary_color": "#1D1234",
          "secondary_color": "#AB1234"
        }
      }
    },
    "*/story_tab_component/*": {
    },
    "*/story_tab_component/story_ring": {
      "progress_color": [
        "#339AF9",
        "#78FA58"
      ],
      "background_color": [
        "#EBECEF"
      ]
    },
    "*/story_tab_component/create_new_story_button": {
      "create_new_story_icon": "plus.png",
      "background_color": "#1243EE"
    },
    "*/*/close_button": {
      "close_icon": "close.png"
    }
  }
}

Global Theme

Currently we only supports light_theme, you can modify primary_color or secondary_color for app theme.

"global_theme": {
  "light_theme": {
    "primary_color": "#FFFFFF",
    "secondary_color": "#AB1234"
  }
}

Configuration ID of Page, Component and Element

We supports three different levels - Page, Component and Element. The format is like page_id/component_id/element_id.

Page ID - We use post suffix and placed at first, it will looks like camera_page/*/*

Component ID - We use component suffix and placed at middle, it will looks like */comment_component/*

Element ID - We use no suffix and placed at last, it will looks like */*/close_button

Customizing Page

You can override Global Theme for a specific page with desired value like below

"camera_page/*/*": {
  "page_theme": {
    "light_theme": {
      "primary_color": "#000000",
      "secondary_color": "#123456"
    }
  }
}

Allowed Page IDs

These are the available Page IDs

"select_target_page/*/*"
"camera_page/*/*"
"creat_story_page/*/*"
"story_page/*/*"

Customizing Component

You can also override Global Theme for a specific component with desired value like below

"*/edit_comment_component/*": {
  "component_theme": {
    "light_theme": {
      "primary_color": "#1D1234",
      "secondary_color": "#AB1234"
    }
  }
}

Allowed Component IDs

These are the available Component IDs

"*/edit_comment_component/*"
"*/comment_tray_component/*"
"*/story_tab_component/*"

Customizing Element

You can specify background_color for an element, and icon if that element has image icon.

"create_story_page/*/aspect_ratio_button": {
    "aspect_ratio_icon": "aspect_ratio.png",
    "background_color": "#80000000"
}

Allowed Component IDs

These are the available Component IDs

"select_target_page/*/back_button"
"camera_page/*/close_button"
"create_story_page/*/back_button"
"create_story_page/*/aspect_ratio_button"
"create_story_page/*/story_hyperlink_button"
"create_story_page/*/hyper_link"
"create_story_page/*/share_story_button"
"story_page/*/progress_bar"
"story_page/*/overflow_menu"
"story_page/*/close_button"
"story_page/*/story_impression_button"
"story_page/*/story_comment_button"
"story_page/*/story_reaction_button"
"story_page/*/create_new_story_button"
"story_page/*/speaker_button"
"*/edit_comment_component/cancel_button"
"*/edit_comment_component/save_button"
"*/hyper_link_config_component/*"
"*/hyper_link_config_component/done_button"
"*/hyper_link_config_component/cancel_button"
"*/story_tab_component/story_ring"
"*/story_tab_component/create_new_story_button"
"*/*/close_button"

Excluding page, component or element

You can exclude UI elements by specifying its config id in excludes in configuration file.

Example: Excluding aspect ratio button from Story Draft page

"excludes": [
    "create_story_page/*/aspect_ratio_button"
]

To allow for more customization, we have now open sourced our UI Kits and deprecated the packaged UI Kit versions that was previously available (2.x.x and below).

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 Open Source UI Kit to customize the visual style

• Get 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 git submodule of Amity 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 latest version of Open Source UIKit (i.e v3.12.0) from old Repository, We suggest you to start pulling changes from new repository instead.

In this case,

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

For Old Users:

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

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

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

Step 1: Reset 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 AmityUIKit / AmitySDK and call 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
git checkout tags/4.0.0-beta01
cd ..
git add .
git commit -m “Update ios uikit opensource submodule”
git push origin master

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

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

If you have trouble finding this, you can post in our community forum at community.amity.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: .global)

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 device for push notifications

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

Amity'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

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.

AmityUIKitManager.unregisterDevice()

Features

Usage

let viewController = AmityCommunityProfilePageViewController
    .make(withCommunityId: "<community-id>")

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

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

Capturing image with camera

Select image from gallery

Recording video with camera

Select video from gallery

Features

Customization

For more details customization, please refer to Customization page.

Usage

let createStoryPage = AmityCreateStoryPage(targetId: "<community-id>", avatar: "<UIImage>")
let viewController = SwiftUIHostingController(rootView: createStoryPage)

val intent = AmityCreateStoryPageActivity.newIntent(
        context = context,
        community = community
)
startActivity(intent)

Features

Customization

Usage

Features

Customization

Usage

Features

Usage

Features

Customization

Usage

Features

To allow for more customization, we have now open sourced our UI Kits and deprecated the packaged UI Kit versions that was previously available (2.x.x and below).

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

Import UI Kit module to your existing project

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

• 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:

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

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

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.

Features

Customization

For more details customization, please refer to Customization page.

Usage

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

AmityStoryTargetPickerFragment.newInstance().build(storyCreationType: String)

Features

Usage

let viewController = AmityCommunityProfilePageViewController
    .make(withCommunityId: "<community-id>")

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

In Amity UIKit 4.0, customization is a pivotal aspect, allowing for extensive personalization across UI elements, components, and pages. Understanding the hierarchy and role of each of these entities is crucial for effectively utilizing the UIKit's capabilities.

Understanding Elements, Components, and Pages

UI Elements:

• Definition: The fundamental building blocks of the user interface.

• Characteristics: Atomic views constitute the most basic UI elements, offering essential interactivity and visual elements but often requiring additional structure to fulfill complete business use cases​​.

• Example: A button or an individual text field.

Components:

• Definition: Combinations of UI elements that serve a specific function.

• Types: Divided into Presentational and Controller components.

  • Presentational Components: Direct renderers, providing straightforward rendering capabilities. They offer high flexibility and are foundational for Controller components​​.

  • Controller Components: Handle complex logic and are pivotal in supporting various business use cases. For example, FeedList or PostView components​​.

• Customization: Both types of components offer diverse customization opportunities, from visual appearance to functional behavior.

Pages:

• Definition: Represent distinct screens within an application, offering a focused set of content and functionality.

• Role: A page comprises a combination of UI elements and components, providing a holistic user experience. It acts as a container for various components and elements tailored to specific user objectives​​.

• Customization: Pages can be tailored in terms of layout, content, and the interactivity of the components they contain.

Customization Options

Feature Settings:

• Scope: Global level.

• Purpose: Configure business-specific settings.

• Example: Allow or restrict certain types of posts or messages​​.

Theme Settings:

• Scope: Global level.

• Purpose: Define the visual appearance of UI elements uniformly.

• Example: Set primary and secondary colors, font family​​.

Element Customization:

• Scope: Local level, per element.

• Purpose: Configure individual UI elements according to specific requirements.

• Limitation: Does not include customization of internal views of an element​​.

Internal View Customization:

• Scope: Local level, specific to Controller components.

• Purpose: Customize internal views within Controller components.

• Example: Altering cells within ConversationList or modifying views in PostView​​.

Event-Driven API and Navigation Management

• Event-Driven API: Allows for maximum adaptability in crafting user journeys, particularly suited for simpler UI scenarios like standalone views​​.

• UIKit Managed Navigation: For more complex UI scenarios, such as pages, the framework autonomously manages flow, navigation, and transitions, leveraging common business logic assumptions​​.