Pin a channel

Channel pinning provides two capabilities:

• Pin a channel in the channel list: Controlled by the isPinned property on NCBaseChannel.
• Pin a channel within a tag group (requires the channel tag feature): Controlled by the isPinned property on NCChannelTagInfo.

Pin a channel in the channel list

Pinning a channel updates the isPinned field on NCBaseChannel and syncs the state to the server. The SDK automatically synchronizes the pinned state across all devices where the user is logged in.

Pin a channel

Call pinWithParams:completion: on a channel instance:

Swift

swift

import NexconnChatSDK

guard let channel = DirectChannel(channelId: "targetUserId") else {
    return
}

let params = PinParams(updateOperationTime: false)
channel.pin(params: params) { error in
    if let error {
        print("Failed to pin: \(error.localizedDescription)")
    } else {
        print("Channel pinned")
    }
}

Objective-C

Objective C

NCDirectChannel *channel = [[NCDirectChannel alloc] initWithChannelId:@"targetUserId"];
NCPinParams *params = [[NCPinParams alloc] initWithUpdateOperationTime:NO];

[channel pinWithParams:params
            completion:^(NCError * _Nullable error) {
    if (error == nil) {
        NSLog(@"Channel pinned");
    } else {
        NSLog(@"Failed to pin: %@", error);
    }
}];

Parameter	Type	Description
params	NCPinParams *	Pin parameters. Set updateOperationTime to control whether pinning updates the channel operation time.
completion	Block	Result callback. nil error means success.

NCPinParams properties

Property	Type	Description
updateOperationTime	BOOL	Whether pinning also updates the channel operation time.

Unpin a channel

Swift

swift

import NexconnChatSDK

guard let channel = DirectChannel(channelId: "targetUserId") else {
    return
}

channel.unpin { error in
    if let error {
        print("Failed to unpin: \(error.localizedDescription)")
    } else {
        print("Channel unpinned")
    }
}

Objective-C

Objective C

NCDirectChannel *channel = [[NCDirectChannel alloc] initWithChannelId:@"targetUserId"];

[channel unpinWithCompletion:^(NCError * _Nullable error) {
    if (error == nil) {
        NSLog(@"Channel unpinned");
    }
}];

Check pinned status

Swift

swift

import NexconnChatSDK

guard let channel = DirectChannel(channelId: "targetUserId") else {
    return
}

let isPinned = channel.isPinned
print("Pinned: \(isPinned)")

Objective-C

Objective C

NCDirectChannel *channel = [[NCDirectChannel alloc] initWithChannelId:@"targetUserId"];
BOOL isPinned = channel.isPinned;

Get all pinned channels

Swift

swift

import NexconnChatSDK

let channelTypes: [NSNumber] = [
    NSNumber(value: ChannelType.direct.rawValue),
    NSNumber(value: ChannelType.group.rawValue)
]

BaseChannel.getPinnedChannels(channelTypes: channelTypes) { channels, error in
    if let error {
        print("Failed to get pinned channels: \(error.localizedDescription)")
    } else {
        print("Pinned channels: \(channels?.count ?? 0)")
    }
}

Objective-C

Objective C

[NCBaseChannel getPinnedChannels:@[@(NCChannelTypeDirect), @(NCChannelTypeGroup)]
                      completion:^(NSArray<NCBaseChannel *> * _Nullable channels, NCError * _Nullable error) {
    if (error == nil) {
        NSLog(@"Pinned channels: %lu", (unsigned long)channels.count);
    }
}];

Listen for pinned status changes

Register an NCChannelHandler to receive pin status sync notifications:

Swift

swift

import NexconnChatSDK

final class DirectChannelPinObserver: NSObject, ChannelHandler {
    func onChannelPinnedSync(_ event: ChannelPinnedSyncEvent) {
        print("Channel \(event.channelIdentifier.channelId) pinned: \(event.isPinned)")
    }
}

// Keep a strong reference to the observer, for example as a property on your manager or view controller.
let observer = DirectChannelPinObserver()
NCEngine.addChannelHandler(identifier: "MyHandler", handler: observer)

Objective-C

Objective C

[NCEngine addChannelHandlerWithIdentifier:@"MyHandler" handler:self];

- (void)onChannelPinnedSync:(NCChannelPinnedSyncEvent *)event {
    NSLog(@"Channel %@ pinned: %@", event.channelIdentifier.channelId, event.isPinned ? @"YES" : @"NO");
}

Pin a channel within a tag group

tip

This feature uses the NCTag instance. Pinning within a tag modifies the NCChannelTagInfo.isPinned field and does not affect the NCBaseChannel.isPinned field.

If your app uses channel tags, users can tag multiple channels and retrieve tag membership from the public SDK. However, the current public NCTag API does not expose pin/unpin operations for a channel inside a tag.

info

Pinning a channel inside a tag group is not currently exposed as a public ObjC API on NCTag. The public tag APIs currently cover tag creation, lookup, channel assignment/removal, unread-count operations, and tagged-channel queries.

Sync empty pinned channels

When a user reinstalls or logs in on a new device, pinned channels may appear in the list, including empty pinned channels.

Control this with the enableSyncEmptyTopConversation property on NCInitParams during initialization. By default, the SDK does not sync empty pinned channels.

tip

If you enable syncing empty pinned channels, pass 0 as startTime for the first page and use the channel's operationTime for subsequent pages.

Swift

swift

import NexconnChatSDK

let initParams = InitParams(appKey: "your_appkey")
initParams.enableSyncEmptyTopConversation = true
NCEngine.initialize(initParams)

Objective-C

Objective C

NCInitParams *initParams = [[NCInitParams alloc] initWithAppKey:@"your_appkey"];
initParams.enableSyncEmptyTopConversation = YES;
[NCEngine initializeWithParams:initParams];