1 of 19

Migration Guides

The following pages contain the migration guides of our SDKs

Web SDK v5.0.0 Migration Guide

iOS UIKit V3.0 Migration Guide

UIKit v3.0.0 is the major release of our UIKit with AmitySDK v6.5.0.

The guide will cover all the breaking changes and migration to this version.

Installation:

Manual Installation:

UIKit v3.0.0 will require RealmSwift.xcframework along with the existing frameworks.

Behavior Changes:

AmityUIKItManager:

AmityChannelEventHandler:

AmityEventHandler:

AmityMessageListViewController:

AmityCommunityProfilePageViewController:

iOS SDK v6.0.0 Migration Guide

This guide is to provide information about breaking changes and how to migrate to the AmitySDK iOS 6.0.0 version.

Installation

Manual Installation

AmitySDK 6.x.x version requires RealmSwift.xcframework along with existing frameworks.

Behaviour Changes

Channel

Channel Creation

Support for Providing custom ID when creating channel is now removed.

Sub Channels:

Now you can create multiple sub-channels inside a channel. Each Sub Channels acts as a separate container for message. The channel itself would act as a default Sub Channel. You can access this default sub channel id through defaultSubChannelId property in class AmityChannel.

Messages

Sending a message in a Channel or Sub Channel now requires subchannelId. If you want to send message in default subchannel (i.e the default channel itself), please use defaultSubChannelId property from AmityChannel.

For sending message in particular AmitySubchannel, you can get its id from subChannelId property.

Interface Changes:

@objc support for all interfaces such as classes, enums, methods, properties are removed. Please create a swift wrapper class to interact with the SDK if your project still uses Objective-C.

All Enums with rawType UInt has been changed to Int
Swift classes

AmityCollection

AmityReaction

AmityClient

AmityContentSettings

Channel

AmityChannel

AmityChannelParticipation

AmityMessage

AmityMessageRepository

AmityMessageEditor

AmityPost

AmityPollRepository

AmityPoll

AmityPollAnswer

AmityPostRepository

AmityFeedRepository

AmityCommunityRepository

AmityCommunity

AmityCommentRepository

AmityComment

AmityUser

AmityUserFollowManager

iOS SDK v6.9.0 Deprecation Note

Deprecated APIs

Deprecated APIs in AmityClient:

Method

Remark

Deprecated APIs in AmityUserNotificationsManager:

Method

Remark

Deprecated APIs in AmityPostRepository:

Method

Remark

Deprecated APIs in AmityCommunityRepository:

Method

Remark

Deprecated APIs in AmityChannelRepository:

Method

Remark

Deprecated APIs in AmitySubChannelRepository:

Method

Remark

Deprecated APIs in AmityCommentRepository:

Method

Remark

Deprecated APIs in AmityChannelModeration:

Deprecated APIs in AmityMessageRepository:

Deprecated APIs in AmityStreamBroadcaster. Use the `AmityVideoBroadcaster` class instead:

iOS SDK v6.8.0 Deprecation Note

Deprecated APIs

AmityCommentRepository:

Methods

Remarks

AmityCommentFlagger

Deprecated APIs in AmityCommentFlagger class. Use APIs in AmityCommentRepository instead.

Methods

Remarks

AmityUserFollowManager

Deprecated APIs in AmityUserFollowManager class. Use APIs in AmityUserRelationship instead.

Methods

Remarks

AmityChannelParticipation

Deprecated APIs in AmityChannelParticipation class. Use APIs in AmityChannelMembership instead.

AmityChannelModeration

AmityMessageEditor

Deprecated APIs in AmityMessageFlagger class. Use APIs in AmityMessageRepository instead.

AmityMessageFlagger

AmitySubChannelRepository

AmityClient

AmityMessageRepository

AmityFeedRepository

AmitySteamRepository

AmityStreamBroadcaster

iOS SDK v6.7.0 Deprecation Note

Deprecated APIs

AmityCommunityRepository:

Methods

Remarks

AmityCommunityParticipation

Deprecated AmityCommunityParticipation class. Use AmityCommunityMembership instead.

Methods

Remarks

AmityCommunityModeration

Methods

Remarks

AmityPostRepository

Methods

Remarks

AmityPostFlagger

Deprecated APIs in AmityPostFlagger class. Use APIs in AmityPostRepository instead.

AmityUserFlagger

Deprecated APIs in AmityUserFlagger class. Use APIs in AmityUserRepository instead.

AmityPollRepository

iOS SDK v6.5.0 Deprecation Note

Deprecated APIs

AmityClient

Methods

Remarks

AmityMessageRepository

Methods

Remarks

AmityUserFlagger

Methods

Remarks

Android SDK v6.0.0 Migration Guide

This guide is to provide information about breaking changes and how to migrate to the AmitySDK Android 6.0.0 version.

Live Objects / Live Collections Changes

As announced here, Deprecation announcements, this version replaces PagedList and RxJava2 with PagingData and RxJava3.

Live capability has been upgraded with RxJava3. Include RxJava3 to your project with this guide, RxJava Getting Started, or use SDK’s extension function to Rx2() to bridge the SDK functions back to RxJava2.

The Paginated collection has been upgraded with PagingData. To consume PaginData, replace Android’s PagedListAdapter with PagingDataAdapter following this guide, Paging V3 migration.

Behaviour Changes

Channel

Create

Channel creation with custom id is no longer supported

Message

Query

Message query from channel is no longer supported. Messages from each channel are migrated to the corresponding channel’s default sub-channel. Refer to Subchannel feature documentation.

StackFromEnd option is no longer supported. To achieve Chat room behaviour, use sortyBy() with the value AmityMessageQuerySortOption.LAST_CREATED and reverse the RecyclerView.

Create

Message creation on the channels is no longer supported. Messages must be created on Subchannels only. Refer to Subchannel feature documentation.

RTE

Automatic subscription to messages on Live and Broadcast channels is no longer supported. To receive real time updates on these channels, explicitly subscribe to the channel. Refer to RTE documentation.

Comment

Create

Comment creation with custom id is no longer supported.

Package Changes

All SDK classes are required to be newly imported into your project as API classes are relocated to com.amity.socialcloud.sdk.api and model classes are relocated to com.amity.socialcloud.sdk.model

Interface Changes

API

AmityChannelRepository

AmityChannelParticipation

AmityChannelMembershipQuery

AmityChannelMemberSearch

AmityMessageRepository

AmityMessageQuery

AmityMessageQuery.Builder

AmityMessageReactionQuery

AmityCoreClient

AmityFileRepository

AmityMyFollowersQuery

AmityMyFollowingsQuery

AmityUserFollowersQuery

AmityUserFollowingsQuery

AmityUserQuery

AmityUserSearch

AmityUserNotification

AmityUserUpdate

AmityCommunityCategoryQuery

AmityCommentRepository

AmityCommentReactionQuery

AmityCommunityQuery

AmityCommunityModeration

AmityMembershipQuery

AmityCommunityMembershipSearch

AmityFeedRepository

AmityPostRepository

AmityCommunityPostQuery

AmityUserPostQuery

AmityGlobalFeedQuery

AmityCustomRankingGlobalFeedQuery

AmityPostReactionQuery

AmityStreamRepository

AmityStreamQuery

Model

AmityChannel

AmityMessage

AmityComment

AmityCommunity

AmityPost

AmityStream

Android SDK v.6.19.0 Deprecation Note

Deprecated APIs

AmityVideoPlayer

Methods

Remarks

AmityStream

Methods

Remarks

Android SDK v6.10.0 Deprecation Note

Deprecated APIs

AmityChannelModeration

Methods

Remarks

AmityCoreClient

Methods

Remarks

AmityUserRepository

Methods

Remarks

AmityCommentRepository

Methods

Remarks

AmityCommentRepository

Methods

Remarks

AmityCommunityModeration()

Methods

Remarks

AmityPollRepository

Methods

Remarks

AmityPostRepository

AmityStreamRepository

Android SDK v6.9.0 Deprecation Note

Deprecated APIs

AmityChannelRepository

Methods

Remarks

AmityMessageRepository

Methods

Remarks

AmityMessage

Methods

AmityMessage.Data.TEXT

Methods

Remarks

AmityMessage.Data.CUSTOM

Methods

Remarks

AmityMessageFlagger()

Methods

Remarks

AmitySubChannelRepository

Methods

Remarks

AmityPostRepository

Android SDK v6.5.0 Deprecation Note

Deprecated APIs

AmityCoreClient

Methods

Remarks

AmityChannelRepository

Methods

Remarks

AmityCommunityRepository

Methods

Remarks

AmityCommentRepository

Methods

Remarks

AmityComment

AmityMessageRepository

AmityMessage

AmityPostRepository

AmityPost

AmityUserRepository

Enum

TS SDK v6.4.6 Deprecation Note

Deprecated APIs

AmityStreamRepository

Methods

Remarks

AmityCommunityRepository

Methods

Remarks

Android SDK v6.0.0 Migration Guide

This guide is to provide information about breaking changes and how to migrate to the AmitySDK Android 6.0.0 version.

Live Objects / Live Collections Changes

As announced here, Deprecation announcements, this version replaces PagedList and RxJava2 with PagingData and RxJava3.

The Paginated collection has been upgraded with PagingData. To consume PaginData, replace Android’s PagedListAdapter with PagingDataAdapter following this guide, Paging V3 migration.

Behaviour Changes

Channel

Create

Channel creation with custom id is no longer supported

Message

Query

Message query from channel is no longer supported. Messages from each channel are migrated to the corresponding channel’s default sub-channel. Refer to Subchannel feature documentation.

StackFromEnd option is no longer supported. To achieve Chat room behaviour, use sortyBy() with the value AmityMessageQuerySortOption.LAST_CREATED and reverse the RecyclerView.

Create

Message creation on the channels is no longer supported. Messages must be created on Subchannels only. Refer to Subchannel feature documentation.

RTE

Comment

Create

Comment creation with custom id is no longer supported.

Package Changes

Interface Changes

API

AmityChannelRepository

Methods

Changes

Remarks

AmityChannelParticipation

Methods

Changes

Remarks

AmityChannelMembershipQuery

Methods

Changes

Remarks

AmityChannelMemberSearch

Methods

Changes

Remarks

AmityMessageRepository

Methods

Changes

Remarks

AmityMessageQuery

Methods

Changes

Remarks

AmityMessageQuery.Builder

Methods

Changes

Remarks

AmityMessageReactionQuery

Methods

Changes

Remarks

AmityCoreClient

Methods

Changes

Remarks

AmityFileRepository

Methods

Changes

Remarks

AmityMyFollowersQuery

Methods

Changes

Remarks

AmityMyFollowingsQuery

Methods

Changes

Remarks

AmityUserFollowersQuery

Methods

Changes

Remarks

AmityUserFollowingsQuery

Methods

Changes

Remarks

AmityUserQuery

Methods

Changes

Remarks

AmityUserSearch

Methods

Changes

Remarks

AmityUserNotification

Methods

Changes

Remarks

AmityUserUpdate

Methods

Changes

Remarks

AmityCommunityCategoryQuery

Methods

Changes

Remarks

AmityCommentRepository

Methods

Changes

Remarks

AmityCommentReactionQuery

Methods

Changes

Remarks

AmityCommunityQuery

Methods

Changes

Remarks

AmityCommunityModeration

Methods

Changes

Remarks

AmityMembershipQuery

Methods

Changes

Remarks

AmityCommunityMembershipSearch

Methods

Changes

Remarks

AmityFeedRepository

Methods

Changes

Remarks

AmityPostRepository

Methods

Changes

Remarks

AmityCommunityPostQuery

Methods

Changes

Remarks

AmityUserPostQuery

Methods

Changes

Remarks

AmityGlobalFeedQuery

AmityCustomRankingGlobalFeedQuery

AmityPostReactionQuery

AmityStreamRepository

AmityStreamQuery

Model

AmityChannel

AmityMessage

AmityComment

AmityCommunity

AmityPost

AmityStream

Web SDK v5.0.0 Migration Guide

This guide is to provide information about breaking changes and how to migrate to the AmitySDK Web 5.0.0 version.

Installation

Following the recent changes with Amity Social Cloud, the Web SDK is now published under a different name.

To install the new v5 version, you will have to run the following commands:

npm uninstall eko-sdk # uninstall version 4
npm install --save @amityco/js-sdk # install version 5

After that, you'll have to change your imports accordingly. You can easily do this by performing a global "search and replace" and put eko-sdk as input and @amityco/js-sdk as output. You should end up with a diff looking like this:

-import Client from 'eko-sdk'
+import Client from '@amityco/js-sdk'

After that, we also renamed the sets of constants for consistency.

Handling Breaking Changes

Don't worry, we didn't change much! Only errors and constants were impacted since we used to prefix them. Aside from this, we did not introduce any change in SDK's logic.

If you are looking for a quick win which will fit 90% of the projects, we recommend you to perform a quick "search and replace" and erase the "Eko" prefix from your code wherever you used it. That is that simple!

For the most precautious, here's an exhaustive list of the names we changed.

Eko Client (optional)

The main object you'll interact with is our SDK Client. This class can be freely renamed since it is the default export of our package (ie: import EkoClient from "eko-sdk") so there should be no problem keeping it like this if you prefer.

In the eventuality that you'd like to keep the name we gave in the source code, please find that we rename the class to ASCClient.

Errors (optional)

Globally found, there will be no need to adapt your code except if you specifically added try catch blocks for those error classes.

Constants (mandatory)

All these can be found as named exports at the root of our package (ie: import { EkoFileType } from "eko-sdk"). You will have to manually change those.

Client

LiveObject

User

File

Reactions

Channel

Message

Community

Post

Comment

Conflicting Names

In case you're already using any of those names in your own codebase, you can easily manage by renaming the named imports with the as keyword.

import { CommentDataType } from './my-own-module'

// use "as" to rename as you see fit and avoid conflicts.
import {
  CommentDataType as ASCCommentDataType,
} from '@amityco/js-sdk'

TS SDK v6.0.0 Migration Guide

This guide is to provide information about breaking changes and how to migrate to the Amity TS SDK 6.0.0 version.

Installation

Using NPM

npm i @amityco/ts-sdk@^6.0.0

Using Yarn

yarn add @amityco/ts-sdk@^6.0.0

Deprecation of RunQuery / CreateQuery

Starting from 6.0.0 we recommend to use API's asynchronously. As it will soon be deprecated. Example:

// before
import { updatePost, runQuery, createQuery } from '@amityco/ts-sdk';

const query = createQuery(updatePost, 'postId', { ...updatedPost });

runQuery(query, callback);

// after v6.0.0
import { PostRepository } from '@amityco/ts-sdk'

const updatedPost = await PostRepository.updatePost('postId', { ...updatedPost });

Real Time Events

The real time events are supported via MQTT, which has a crucial difference in how it works compared to web sockets. This is, events are not broadcast-ed to all users. So this means that you only get real time event updates to those topics that you subscribe to.

Note: Some exceptions to this are message events and smart feed events. If you are unsure if subscription is required for a particular topic, check the code-snippet for that particular API for details.

There are also other limitations to getting RTE's, example: you cannot subscribe to events for a community that you are not a member of. Check documentation for full details.

You can read more about MQTT here: https://mqtt.org/

/*
 * Whenever you notice similar code block in the code snippets it indicates that you 
 * subscribing to a particular topic, which in turn let's the server know that you
 * would require real time events for this topic
*/

subscribeTopic(getUserTopic(user, SubscriptionLevels.POST), () => {
    // use callback to handle errors with event subscription
}),

Live Object

Although live objects were introduced prior to v6. All getter methods for singular objects (example getPost) will now return a subscribe-able object.

This means that if an object gets updated and you have subscribed to real time events, the object will get updated automatically via real time events.

If for your use case you don't require any real time updates, you can unsubscribe immediately. For further information about Live Object, please visit #live-object page.

Getting Real Time Updates for an Object

import { PostRepository, subscribeTopic, getPostTopic } from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

const disposer: Amity.Unsubscriber[] = [];

const GetPost: FC<{ postId: string }> = ({ postId }) => {
  const [post, setPost] = useState<Amity.Post>();

  useEffect(() => {

    const unsubscribePost = PostRepository.getPost(postId, ({ data }) => {
     const { post, loading, error } = data
     
     if (post) {
       /*
       * This step is important if you wish to recieve real time updates
       * Here, you are letting the server know that you wish to recieve real time
       * updates regarding this post
       */
       disposers.push(subscribeTopic(getPostTopic(post)))
       
       setPost(post)
     }
    });
    
    disposers.push(unsubscribePost);
  }, [postId]);

  return null;
};

Getting the object only once

import { PostRepository } from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

const GetPostOnce: FC<{ postId: string }> = ({ postId }) => {
  const [post, setPost] = useState<Amity.Post>();

  useEffect(() => {
    const unsubscribePost = PostRepository.getPost(postId, ({ data }) => {
     const { post, loading, error } = data
     
     if (post) {       
       setPost(post)
     }
    });
    
    unsubscribePost()
  }, [postId]);

  return null;
};

Live Collection

Although live collections were introduced prior to v6. All query methods for collection of objects (example getPosts) will now return a subscribe-able collection.

This means that if an object in the collection gets updated and you have subscribed to real time events, the collection will get updated automatically via real time events.

If for your use case you don't require any real time updates, you can unsubscribe immediately. Similar to live objects above. For further information about Live Object, please visit #live-collection page.

Getting Real Time updates for a collection

import {
  PostRepository,
  subscribeTopic,
  getUserTopic,
  getCommunityTopic,
  SubscriptionLevels,
} from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

const disposers: Amity.Unsubscriber[] = [];

const GetPosts: FC<{ targetId: string; targetType: string }> = 
({ targetId, targetType }) => {
  const [posts, setPosts] = useState<Amity.Post[]>();

  useEffect(() => {
    const unsubscribe = PostRepository.getPosts(
      { targetId, targetType },
      ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
        setPosts(posts);
        /*
         * this is only required if you want real time updates for each
         * post in the collection
         */
        subscribePostTopic(targetType, targetId);
      },
    );

    disposers.push(unsubscribe);

    return () => {
      disposers.forEach(fn => fn());
    };
  });

  return null;
};

const subscribePostTopic = (targetType: string, targetId: string) => {
  if (isSubscribed) return;

  if (targetType === 'user') {
    const user = {} as Amity.User; // use getUser to get user by targetId
    disposers.push(
      subscribeTopic(getUserTopic(user, SubscriptionLevels.POST), () => {
        // use callback to handle errors with event subscription
      }),
    );
    return;
  }

  if (targetType === 'community') {
    // use getCommunity to get community by targetId
    const community = {} as Amity.Community; 
    disposers.push(
      subscribeTopic(getCommunityTopic(community, SubscriptionLevels.POST), () => {
        // use callback to handle errors with event subscription
      }),
    );
  }
};

Getting paginated collection without and real time updates

import {
  PostRepository,
  subscribeTopic,
  getUserTopic,
  getCommunityTopic,
  SubscriptionLevels,
} from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

const GetPosts: FC<{ targetId: string; targetType: string }> = 
({ targetId, targetType }) => {
  const [posts, setPosts] = useState<Amity.Post[]>();

  useEffect(() => {
    const unsubscribe = PostRepository.getPosts(
      { targetId, targetType },
      ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
        if (posts)
          setPosts(posts);
        
        // to get next page use onNextPage()
      },
    );

    unsubscribe()
  });

  return null;
};

Introducing Repositories

Starting from 6.0.0, you will no longer be able to import individual SDK API's. You'll need to import the required API from it's respective Repositories.

Client

import { Client } from '@amityco/ts-sdk

UserRepository

import { UserRepository } from '@amityco/ts-sdk

FileRepository

import { FileRepository } from '@amityco/ts-sdk

ReactionRepository

import { ReactionRepository } from '@amityco/ts-sdk

CommunityRepository

import { CommunityRepository } from '@amityco/ts-sdk

StreamRepository

import { StreamRepository } from '@amityco/ts-sdk

PostRepository

import { PostRepository } from '@amityco/ts-sdk

CommentRepository

import { CommentRepository } from '@amityco/ts-sdk

PollRepository

import { PollRepository } from '@amityco/ts-sdk

ChannelRepository

import { ChannelRepository } from '@amityco/ts-sdk

MessageRepository

import { MessageRepository } from '@amityco/ts-sdk