iOS SDK v7 → v8 Migration Guide

Xcode 26 compatibility is fully restored in v8. The cache layer has been migrated from Realm to Core Data, eliminating all Realm dependencies and removing the need for per-Xcode-version SDK variants.

Code blocks in this migration guide compare v7 and v8 shapes. v7 snippets intentionally reference removed APIs; use the v8 snippets for new code.

What changed in v8

SDK v8 is a major release focused on three goals:

Remove Realm — the cache layer is now powered by Core Data, restoring Xcode forward compatibility and removing a heavyweight dependency from your project.
Modernise the API surface — constructors, async methods, and model objects follow consistent, Swift-idiomatic patterns.
Expand product tagging and room capabilities — new APIs for product tags, room management, and co-host permissions.

Installation

SDK

Realm and RealmSwift are no longer required as of v8.

Method	Steps
Swift Package Manager	No changes needed. Install using the v8 release tag. Realm is not installed by default.
Manual (xcframework)	Remove `Realm.xcframework` and `RealmSwift.xcframework` from your project. Embed the new `AmitySDK.xcframework` as usual.

Minimum iOS target: 14.0

UIKit

Method	Steps
Swift Package Manager	No changes needed. Install using the v8 UIKit release tag.
Manual (xcframework)	Remove `Realm.xcframework` and `RealmSwift.xcframework`. Embed the new `AmitySDK.xcframework` as usual.
Open Source	`Realm.xcframework` and `RealmSwift.xcframework` are no longer installed through the `SharedFrameworks` Package.swift file.

Minimum iOS target: 14.0

Global breaking changes

These patterns apply across the entire SDK. Per-class sections below only document changes beyond these rules.

1. Client removed from constructors

All repositories and managers no longer accept an AmityClient parameter. The SDK manages the client internally.

// v7
let repo = AmityMessageRepository(client: client)
let mod  = AmityCommunityModeration(client: client, andCommunity: communityId)

// v8
let repo = AmityMessageRepository()
let mod  = AmityCommunityModeration(communityId: communityId)

2. Mutating methods return `Void`

Methods that previously returned Bool to indicate success now return Void. A successful call means success; any failure throws an error.

// v7
let success = try await repo.softDeleteMessage(withId: id) // Bool

// v8
try await repo.softDeleteMessage(withId: id) // Void — throws on failure

3. Completion handlers replaced with async/await

Use async/await directly instead of callback-based completion handlers when enabling features or reading settings.

// v7
manager.enable(completion: { error in ... })
let _ = manager.getSettings(completion: { settings in ... })

// v8
try await manager.enable()
let settings = try await manager.getSettings()

4. Model objects are immutable value snapshots

model and client properties removed from all model classes.
All properties changed from var to let. Exceptions are noted per class.
Timestamp properties (createdAt, updatedAt, editedAt, etc.) changed from Date to Date?.

5. `AmityCollection` observe callback signature changed

AmityCollectionChange has been removed. The callback no longer delivers per-change index information.

// v7
collection.observe { collection, change, error in ... }

// v8
collection.observe { collection, error in ... }

Renamed classes

v7	v8
`AmityChannelQuery`	`AmityChannelQueryOptions`
`AmityChannelUpdateBuilder`	`AmityChannelUpdateOptions`
`AmityCommunityChannelBuilder`	`AmityCommunityChannelCreateOptions`
`AmityConversationChannelBuilder`	`AmityConversationChannelCreateOptions`
`AmityDefaultChannelBuilder`	`AmityDefaultChannelCreateOptions`
`AmityLiveChannelBuilder`	`AmityLiveChannelCreateOptions`
`AmityRawFile`	`AmityFile`
`AmityUserUpdateBuilder`	`AmityUserUpdateOptions`

New classes

Class	Description
`AmityFile`	Replaces `AmityRawFile`. Adds `fileUrl`, `altText`, `feedType`, `status`, `videoUrl`, `attributes`.
`AmityMetadataMapper`	Replaces the deprecated `AmityMentionMapper`. Supports both mentions and hashtags.
`AmityTextProductTag`	A product tag embedded in post text: `productId`, `product`, `index`, `length`.
`AmityMediaProductTag`	A product tag attached to a media item: `productId`, `product`.
`AmityAttachmentProductTags`	Container for per-attachment product tags when creating or editing posts.
`AmityProduct`	New product model: `productId`, `productName`, `productUrl`, `status`, `price`, `currency`, `thumbnailUrl`, etc.
`AmityProductCatalogueSetting`	Product catalogue setting from the server: `enabled: Bool`.
`AmityRoomResolution`	Stream resolution info for a room: `aspectRatio`, `width`, `height`.

Removed APIs

Class	Removed	Replacement
`AmityCollection`	`count()`	`snapshots.count`
`AmityCollection`	`object(at:)`	`snapshots[index]`
`AmityCollection`	`allObjects()`	`snapshots`
`AmityChannel`	`getPreviewMembers()`	`previewMembers` property
`AmityCollectionChange`	Entire class	—
`AmityAdImage`	Entire class	—
`AmityUserRepository`	`userRelationship` property	Instantiate `AmityUserRelationship()` directly

Per-class changes

Only changes beyond the global breaking changes are listed here.

AmityChannel

Change	Details
`currentMembership` renamed	→ `currentMember: AmityChannelMember?`
`previewMembers` added	`[AmityChannelMember]` — replaces the removed `getPreviewMembers()` method
`attachedToPost`, `attachedToStream` removed	No replacement
`attachedToRoom`	Now externally read-only (`public private(set) var`)

AmityChannelMembership

Init signature changed: init(channelId: String) — no client parameter.

AmityChannelModeration

Init signature changed: init(channelId: String) — no client parameter.

AmityChannelNotificationsManager

Init signature changed: init(channelId: String)
getSettings() return type is now AmityChannelNotificationSettings

AmityChannelQueryOptions (was AmityChannelQuery)

All options must now be provided at initialisation rather than mutated after the fact.

// v7 — mutate after init
let query = AmityChannelQuery()
query.types = [...]

// v8 — configure at init
let options = AmityChannelQueryOptions(
    types: [...],
    filter: .all,
    includingTags: [],
    excludingTags: [],
    includeDeleted: false
)

AmityChannelRepository

Method	Change
`getChannels(with:)`	Parameter type: `AmityChannelQuery` → `AmityChannelQueryOptions`
`createChannel(with:)`	Parameter type: `AmityChannelBuilder` → `AmityChannelCreateOptions`
`editChannel(with:)`	Parameter type: `AmityChannelUpdateBuilder` → `AmityChannelUpdateOptions`

AmityClient

editUser(_:) parameter type changed: AmityUserUpdateBuilder → AmityUserUpdateOptions

AmityComment

links: [AmityLink] added
isInvalidated removed

AmityCommentCreateOptions

links: [AmityLink]? added.

AmityCommentQueryOptions

pageSize: Int = 20 added.

AmityCommentUpdateOptions

links: [AmityLink]? added.

AmityCommunity

user: AmityUser? added (the community creator/owner)
event property removed

AmityCommunityMembership

Init signature changed: init(communityId: String)
getMembers(...) and searchMembers(...) gain excludingRoles: [String] = []

AmityCommunityModeration

Init signature changed: init(communityId: String) — no client parameter.

AmityCommunityNotificationsManager

Init signature changed: init(communityId: String)

v7	v8
`enable(for events:completion:)`	`enable(events:) async throws`
`disable(completion:)`	`disable() async throws`
`getSettingsWithCompletion(_:)`	`getSettings() async throws -> AmityCommunityNotificationSettings`

AmityCommunityRepository

v7	v8
`deleteCommunity(withId:completion:)`	`deleteCommunity(withId:) async throws`
`joinCommunity(withId:) async throws -> Bool`	No longer deprecated. Returns `Void`.
`leaveCommunity(withId:) async throws -> Bool`	Returns `Void`.

AmityFeedRepository

v7	v8	Notes
`getMyFeedSorted(feedSources:dataTypes:by sortBy:...)`	`getMyFeed(feedSources:dataTypes:sortBy:...)`	Renamed; `by sortBy:` label removed
`getUserFeed(...)`	`getUserFeed(...)`	Added `untilAt: Date?`
`getCommunityFeed(...)`	`getCommunityFeed(...)`	Added `untilAt: Date?`

AmityFileRepository

getFile(fileId:) return type changed: AmityRawFile → AmityFile

AmityImageStoryCreateOptions

Typo fixed: tartgetId → targetId. Update all call sites.

AmityLiveChannelCreateOptions (was AmityLiveChannelBuilder)

setVideoStreamId(_:) is deprecated. Use setRoomId(_:) instead.

AmityMentionMapper (deprecated)

Still available but deprecated. Migrate to AmityMetadataMapper.

Deprecated	Replacement
`AmityMentionMapper.mentions(fromMetadata:)`	`AmityMetadataMapper.mentions(fromMetadata:)`
`AmityMentionMapper.metadata(from:)`	`AmityMetadataMapper.metadata(mentions:hashtags:)`

AmityMetadataMapper also adds hashtags(fromMetadata:) -> [AmityHashtag].

AmityMessageRepository

v7	v8
`deleteFailedMessages(completion:)`	`deleteFailedMessages() async throws`
`setTags(messageId:tags:completion:)`	`setTags(messageId:tags:) async throws`
`flagMessage(withId:) async throws -> Bool`	No longer deprecated. Returns `Void`.

AmityPost

postData type renamed: AmityPost.Data → AmityPost.PostData
pinnedProductId: String? added
eventId: String? added
isInvalidated removed
Remaining mutable properties: postData, analytics, syncState, mentionees, links

AmityPostQueryOptions

untilAt: Date? added.

AmityPostRepository

All createXxxPost(...) and editPost(...) methods gain:

productTags: [AmityTextProductTag]?
attachmentProductTags: AmityAttachmentProductTags? (where applicable)

Additional changes:

Change	Details
`flagPost(withId:)` deprecated variant removed	Use `flagPost(withId:reason:) async throws`
`createRoomPost(...)` added	Dedicated method for room/co-host posts using `AmityRoomPostBuilder`
`pinProduct(postId:productId:) async throws -> AmityPost` added	Pin a product to a post
`unpinProduct(postId:) async throws -> AmityPost` added	Remove the pinned product from a post
`updateProductTags(postId:productTags:) async throws -> AmityPost` added	Update media product tags on a post

AmityRoom

thumbnail: AmityImageData? added
liveThumbnailUrl: String? added
liveResolution: AmityRoomResolution? added
recordedResolution: AmityRoomResolution? added
isInvalidated removed
channel and post are now externally read-only (public private(set) var)

AmityRoomParticipant

canManageProductTags: Bool added.

AmityRoomPresenceRepository

Init signature changed: init(roomId: String) — no client parameter.

AmityRoomRepository

New method: updateCohostPermissions(roomId:cohostId:canManageProductTags:) async throws -> AmityRoom

AmityStreamRepository

disposeStream(withId:completion:) → disposeStream(withId:) async throws -> AmityStream

AmitySubChannelQueryOptions

Init gains new parameters: init(channelId:isDeleted:excludeDefaultSubChannel:) — both new parameters default to false.

AmityUser

isBanned removed
Added: internalId: String, permissions: [String], path: String, blockedAt: Date?, avatar: AmityImageData?

AmityUserNotificationsManager

enable(for modules:) returns Void
disableAllNotifications() returns Void

AmityUserRelationship

follow(withUserId:), unfollow(withUserId:), acceptMyFollower(withUserId:), declineMyFollower(withUserId:) — return type changed from (Bool, AmityFollowResponse) to AmityFollowResponse
blockUser(userId:) and unblockUser(userId:) are now @MainActor

AmityVideoStoryCreateOptions

Typo fixed: tartgetId → targetId. Update all call sites.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

iOS SDK v7 → v8 Migration Guide

What changed in v8

Installation

SDK

UIKit

Global breaking changes

1. Client removed from constructors

2. Mutating methods return `Void`

3. Completion handlers replaced with async/await

4. Model objects are immutable value snapshots

5. `AmityCollection` observe callback signature changed

Renamed classes

New classes

Removed APIs

Per-class changes

​What changed in v8

​Installation

​SDK

​UIKit

​Global breaking changes

​1. Client removed from constructors

​2. Mutating methods return Void

​3. Completion handlers replaced with async/await

​4. Model objects are immutable value snapshots

​5. AmityCollection observe callback signature changed

​Renamed classes

​New classes

​Removed APIs

​Per-class changes

What changed in v8

Installation

SDK

UIKit

Global breaking changes

1. Client removed from constructors

2. Mutating methods return `Void`

3. Completion handlers replaced with async/await

4. Model objects are immutable value snapshots

5. `AmityCollection` observe callback signature changed

Renamed classes

New classes

Removed APIs

Per-class changes