​

Sync Chat SDK for iOS: Quickstart

With the Sync Chat SDK for iOS, you can quickly add high-quality, real-time text chat to your app. Sync SDKs offer a ready-to-use, best-in-class user experience that you can customize completely.

The prebuilt UI panel has expanded and collapsed states:

Expanded state
Collapsed state

Before starting

Minimum versions

  • iOS: 14.0

  • Xcode 13.3

Install the SDK

  1. Open the Xcode workspace for your app.

  2. Click File, then click Add Packages.

  3. Copy and paste this URL into the search box:

    https://github.com/aircoreio/aircore-chat-panel-ios

  4. Select the Up to Next Major Version dependency rule.

  5. Click Add Package.

  6. You may see the Choose Package Products dialog. Click Add Package.

  7. If you have issues with building after adding the package:

    Open the File menu, then Packages, then click Reset Package Caches.

Authenticate

This guide uses a publishable API key for a quick setup. To get your API key:

  1. Create an app in the Developer Console.

  2. Copy your publishable API key and use it in the next section.

Copying a publishable API key from the console.

For an overview of API keys, see Authentication.

Set up your app

Create the client

The Client object is the primary controller that powers this SDK. The client can seamlessly integrate your existing user and channel models.

You can use the client to:

  • Configure user metadata
  • Join a channel to connect to a real-time session with other users
  • Control logging
  • Listen to events that happen behind the scenes

Use a publishable API key to create the client:

import AircoreChatPanel

// Use a publishable API key directly from the Developer Console
let client = Client.create(publishableKey: key, userID: userID)

For more detailed security controls, you can use a secret API key instead. See Customization.

Set user properties

After creating the Client, set these properties to represent the user:

client.userDisplayName = "Jane Doe"
client.userAvatarURL = URL(string: "http://user-profile-picture.png")

Set up the panel

Set up the UI text

Create a ChatPanelConfiguration object to control the UI text and default behavior. You only need to specify the parameters that you want to customize.

let config = ChatPanelConfiguration(
    // All parameters are optional. Add parameters that you want to customize.
    panelTitle: "My Channel",
    panelSubtitle: "My Channel is a happy space where people can have fun"
)

You can change any text on the panel. See Customize the UI text.

Set the theme

By default, the panel uses a light theme. To use a dark theme, create an optional Theme object:

let myTheme = Theme.dark()

You can also create a custom theme. See Customize the theme.

Customize the user experience

You can customize how users interact with the chat. When a user joins a chat, they can see the full message history for the channel.

Disable sending messages

By default, all users can send messages. To change this, set canSendMessage to false.

Automatically join the chat

By default, users can preview the chat. To join, they must press a button. When users join, they appear on the panel.

To have users join automatically, set previewBeforeJoin to false.

Connect and show the panel

Connect to a channel

A channel represents a group of users. See Channels for a general overview.

To connect the client to a channel, use the connect() method.

If you're using a secret API key, you need a session auth token that matches the channel. When you request a token, use the same channel ID.

client.connect(channelID: channel)

Create the panel object

You can now create the ChatPanel object, which shows the panel in your existing view controller:

client.connect(channelID: channel)

let panel = ChatPanel(
    client: client,
    channelID: channel,
    configuration: configuration,
    theme: myTheme // Optional
)

panel.present(in: self, style: .bottomBar)

Disconnect and reconnect to a channel

You can disconnect and reconnect to the same channel.

To disconnect, call the disconnect() method. To reconnect, call connect() using the same channelID.

// Disconnect from a channel
client.disconnect(fromChannelID: channel)

// Reconnect to the channel
client.connect(channelID: channel)

Switch to a new channel

To switch to a new channel, use a new client:

  1. Tear down the panel and client objects (see Tear down and clean up below).

  2. Start again with a new client (see Create the client above).

Respond to notifications and errors

You can subscribe to events and errors and respond accordingly:

client.on(.localUserJoined) { channelID, userID in
    print("I just joined a call!")
}

client.on(.sessionAuthTokenNearingExpiry) { channelID, userID in
    // Get a new session auth token from your server and update the client
}

client.on(.sessionAuthTokenInvalid) { channelID, userID in
    // Get a valid session auth token from your server and update the client
}

client.onError { channelID, error in
    // Handle any errors
}

See the complete references for events and errors.

Tear down and clean up

To tear down the panel and client:

  1. Use the panel's destroy() method.

  2. Then, use the client's destroy() method.

// Tear down the panel
panel.destroy()

// Tear down the client
// This disconnects automatically from all connected channels
client.destroy()

More info