|
| 1 | +--- |
| 2 | +title: SDK setup |
| 3 | +meta_description: 'Install, authenticate and instantiate the Chat SDK.' |
| 4 | +product: chat |
| 5 | +languages: |
| 6 | + - javascript |
| 7 | + - react |
| 8 | + - swift |
| 9 | + - kotlin |
| 10 | +--- |
| 11 | + |
| 12 | +Use these instructions to install, authenticate and instantiate the Chat SDK. |
| 13 | + |
| 14 | +<aside data-type="note"> |
| 15 | + <p>If you have any feedback or feature requests, "let us know.":https://forms.gle/SmCLNFoRrYmkbZSf8</p> |
| 16 | +</aside> |
| 17 | + |
| 18 | +h2(#authentication). Authentication |
| 19 | + |
| 20 | +An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using "token authentication":/docs/auth/token. |
| 21 | + |
| 22 | +<aside data-type="important"> |
| 23 | + <p> |
| 24 | + The examples use basic authentication to demonstrate features for convenience. In your own applications, basic |
| 25 | + authentication should never be used on the client-side as it exposes your Ably API key. Instead use token |
| 26 | + authentication. |
| 27 | + </p> |
| 28 | +</aside> |
| 29 | + |
| 30 | +"Sign up":https://ably.com/sign-up to Ably to create an API key in the dashboard or use the "Control API":/docs/account/control-api to create an API key programmatically. |
| 31 | + |
| 32 | +API keys and tokens have a set of "capabilities":/docs/auth/capabilities assigned to them that specify which operations, such as subscribe or publish can be performed on which resources. To use the Chat SDK, the API key requires the following capabilities depending on which features are being used: |
| 33 | + |
| 34 | +|_. Feature |_. Capabilities | |
| 35 | +| Send and receive messages | Publish, Subscribe | |
| 36 | +| Message history | Subscribe, History | |
| 37 | +| Online status | Subscribe, Presence | |
| 38 | +| Room occupancy | Subscribe, Channel Metadata | |
| 39 | +| Typing indicators | Publish, Subscribe, Presence | |
| 40 | +| Room reactions | Publish, Subscribe | |
| 41 | + |
| 42 | +When setting the capabilities for Chat, you need to apply them to either a wildcard resource, or a wildcard resource prefixed with the chat namespace, for example: |
| 43 | + |
| 44 | +- @[chat]_@ and @_@, or |
| 45 | +- @[*]\*@ |
| 46 | + |
| 47 | +h2(#install). Install |
| 48 | + |
| 49 | +The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably. |
| 50 | + |
| 51 | +blang[javascript,react]. |
| 52 | +h3(#npm). NPM |
| 53 | + |
| 54 | +Install the Pub/Sub SDK and the Chat SDK: |
| 55 | + |
| 56 | +```[sh] |
| 57 | +npm install @ably/chat |
| 58 | +``` |
| 59 | + |
| 60 | +Import the SDKs into your project: |
| 61 | + |
| 62 | +```[javascript] |
| 63 | +import * as Ably from 'ably'; |
| 64 | +import { ChatClient } from '@ably/chat'; |
| 65 | +``` |
| 66 | + |
| 67 | +```[react] |
| 68 | +import * as Ably from 'ably'; |
| 69 | +import { ChatClient, ChatClientProvider} from '@ably/chat'; |
| 70 | +``` |
| 71 | + |
| 72 | +blang[swift,kotlin]. |
| 73 | + |
| 74 | +blang[javascript]. |
| 75 | +h3(#cdn). CDN |
| 76 | + |
| 77 | +Reference the Pub/Sub SDK and the Chat SDK within your HTML file: |
| 78 | + |
| 79 | +```[html] |
| 80 | +<script src="https://cdn.ably.com/lib/ably.min-2.js"></script> |
| 81 | +<script src="https://cdn.ably.com/lib/ably-chat.umd.cjs-0.js"></script> |
| 82 | +<script> |
| 83 | + const realtime = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'}); |
| 84 | + const chatClient = new AblyChat.ChatClient(realtime); |
| 85 | +
|
| 86 | +</script> |
| 87 | +``` |
| 88 | + |
| 89 | +blang[swift]. |
| 90 | +h3(#spm). Swift Package Manager |
| 91 | + |
| 92 | +The SDK is distributed as a Swift Package and can be installed using Xcode or by adding it as a dependency in your package’s @Package.swift@. |
| 93 | + |
| 94 | +To install the @ably-chat-swift@ package in your Xcode Project: |
| 95 | +_ Paste @https://github.com/ably/ably-chat-swift@ in the Swift Packages search box (Xcode project → Swift Packages.. . → @+@ button). |
| 96 | +_ Select the Ably Chat SDK for your target. |
| 97 | + |
| 98 | +To install the @ably-chat-swift@ package in another Swift Package, add the following to your @Package.swift@: |
| 99 | + |
| 100 | +```[swift] |
| 101 | +.package(url: "https://github.com/ably/ably-chat-swift", from: "0.1.0"), |
| 102 | +``` |
| 103 | + |
| 104 | +Import the SDK: |
| 105 | + |
| 106 | +```[swift] |
| 107 | +import AblyChat |
| 108 | +``` |
| 109 | + |
| 110 | +blang[kotlin]. |
| 111 | +h3(#gradle). Gradle |
| 112 | + |
| 113 | +The Ably Chat SDK is available on the Maven Central Repository. To include the dependency in your project, add the following to your @build.gradle.kts@ file: |
| 114 | + |
| 115 | +```[kotlin] |
| 116 | + implementation("com.ably.chat:chat-android:0.2.0") |
| 117 | +``` |
| 118 | + |
| 119 | +For groovy: |
| 120 | + |
| 121 | +```[kotlin] |
| 122 | + implementation 'com.ably.chat:chat-android:0.2.0' |
| 123 | +``` |
| 124 | + |
| 125 | +h2(#instantiate). Instantiate a client |
| 126 | + |
| 127 | +Instantiate a realtime client using the Pub/Sub SDK and pass the generated client into the Chat constructor. |
| 128 | + |
| 129 | +blang[react]. |
| 130 | +Pass the @ChatClient@ into the "@ChatClientProvider@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatClientProvider.html. The @ChatClient@ instance will be available to all child components in your React component tree. |
| 131 | + |
| 132 | +blang[javascript,swift,kotlin]. |
| 133 | + |
| 134 | +```[javascript] |
| 135 | +import { LogLevel } from '@ably/chat' |
| 136 | +
|
| 137 | +const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'}); |
| 138 | +const chatClient = new ChatClient(realtimeClient, { logLevel: LogLevel.Error }); |
| 139 | +``` |
| 140 | + |
| 141 | +```[react] |
| 142 | +import { LogLevel } from '@ably/chat' |
| 143 | +
|
| 144 | +const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'}); |
| 145 | +const chatClient = new ChatClient(realtimeClient, { logLevel: LogLevel.Error }); |
| 146 | +
|
| 147 | +const App = () => { |
| 148 | + return ( |
| 149 | + <ChatClientProvider client={chatClient}> |
| 150 | + <RestOfYourApp /> |
| 151 | + </ChatClientProvider> |
| 152 | + ); |
| 153 | +}; |
| 154 | +``` |
| 155 | + |
| 156 | +```[swift] |
| 157 | +let realtimeOptions = ARTClientOptions() |
| 158 | +realtimeOptions.key = "{{API_KEY}}" |
| 159 | +realtimeOptions.clientId = "<clientId>" |
| 160 | +let realtime = ARTRealtime(options: realtimeOptions) |
| 161 | +let chatClient = DefaultChatClient(realtime: realtime, clientOptions: nil) |
| 162 | +``` |
| 163 | + |
| 164 | +```[kotlin] |
| 165 | +import com.ably.chat.ChatClient |
| 166 | +import io.ably.lib.realtime.AblyRealtime |
| 167 | +import io.ably.lib.types.ClientOptions |
| 168 | +
|
| 169 | +val realtimeClient = AblyRealtime( |
| 170 | + ClientOptions().apply { |
| 171 | + key = "{{API_KEY}}" |
| 172 | + clientId = "<clientId>" |
| 173 | + }, |
| 174 | +) |
| 175 | +
|
| 176 | +val chatClient = ChatClient(realtimeClient) |
| 177 | +``` |
| 178 | + |
| 179 | +A "@ClientOptions@":/docs/api/realtime-sdk#client-options object may be passed to the Pub/Sub SDK instance to further customize the connection, however at a minimum you must set an API key and provide a @clientId@ to ensure that the client is "identified":/docs/auth/identified-clients. |
| 180 | + |
| 181 | +In many cases, a users unique application-specific identifier may be used as the `clientId` to provide consistent identification for clients across your application. |
| 182 | + |
| 183 | +Additional options can also be passed to the Chat client to customize the following properties: |
| 184 | + |
| 185 | +blang[javascript,react]. |
| 186 | +|_. Property |_. Description | |
| 187 | +| logHandler | The function to call for each line of "log output":#logging. The default is @console.log@. | |
| 188 | +| logLevel | The verbosity of the "log output":#logging. Options are; @trace@, @debug@, @info@, @warn@, @error@ or @silent@. The default is @error@. | |
| 189 | + |
| 190 | +blang[swift]. |
| 191 | +|_. Property |_. Description | |
| 192 | +| logHandler | This is your own custom log handler conforming to the @LogHandler@ protocol. A single @log@ function is called for each line of "log output":#logging. The default implementation uses Swift's @Logger@. | |
| 193 | +| logLevel | The verbosity of the "log output":#logging. Options are; @.trace@, @.debug@, @.info@, @.warn@, @.error@ or @.silent@. The default is @.error@. | |
| 194 | + |
| 195 | +blang[kotlin]. |
| 196 | +|_. Property |_. Description | |
| 197 | +| logHandler | This is your own custom log handler conforming to the @LogHandler@ interface. A single @log@ function is called for each line of "log output":#logging. The default implementation uses Android's @Log@. | |
| 198 | +| logLevel | The verbosity of the "log output":#logging. Options are; @Trace@, @Debug@, @Info@, @Warn@, @Error@ or @Silent@. The default is @Error@. | |
| 199 | + |
| 200 | +h2(#logging). Logging |
| 201 | + |
| 202 | +Set the @logHandler@ and @logLevel@ properties when "instantiating a client":#instantiate to configure your log handler: |
| 203 | + |
| 204 | +```[javascript] |
| 205 | +const ably = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'}); |
| 206 | +const chatClient = new ChatClient(ably, {logHandler: logWriteFunc, logLevel: 'debug' }); |
| 207 | +``` |
| 208 | + |
| 209 | +```[react] |
| 210 | +import * as Ably from 'ably'; |
| 211 | +import { ChatClientProvider, LogLevel } from '@ably/chat'; |
| 212 | +
|
| 213 | +const ably = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'}); |
| 214 | +const chatClient = new ChatClient(ably, {logHandler: logWriteFunc, logLevel: 'debug' }); |
| 215 | +
|
| 216 | +const App = => { |
| 217 | + return ( |
| 218 | + <ChatClientProvider client={chatClient}> |
| 219 | + <RestOfYourApp /> |
| 220 | + </ChatClientProvider> |
| 221 | + ); |
| 222 | +}; |
| 223 | +``` |
| 224 | + |
| 225 | +```[swift] |
| 226 | +let realtimeOptions = ARTClientOptions() |
| 227 | +realtimeOptions.key = "{{API_KEY}}" |
| 228 | +realtimeOptions.clientId = "<clientId>" |
| 229 | +let realtime = ARTRealtime(options: realtimeOptions) |
| 230 | +let clientOptions = ClientOptions(logHandler: SomeLogHandler(), logLevel: .debug) |
| 231 | +return DefaultChatClient(realtime: realtime, clientOptions: clientOptions) |
| 232 | +``` |
| 233 | + |
| 234 | +```[kotlin] |
| 235 | +val realtimeClient = AblyRealtime( |
| 236 | + ClientOptions().apply { |
| 237 | + key = "{{API_KEY}}" |
| 238 | + clientId = "<clientId>" |
| 239 | + }, |
| 240 | +) |
| 241 | +val chatOptions = com.ably.chat.ClientOptions( |
| 242 | + logHandler = CustomLogHandler(), // Implements com.ably.chat.LogHandler interface |
| 243 | + logLevel = LogLevel.Debug, |
| 244 | +) |
| 245 | +val chatClient = ChatClient(realtimeClient, chatOptions) |
| 246 | +``` |
| 247 | + |
| 248 | +blang[javascript,react]. |
| 249 | +The @logHandler@ property is your own function that will be called for each line of log output generated by the Chat SDK. |
| 250 | + |
| 251 | +blang[swift,kotlin]. |
| 252 | +The @logHandler@ property is your custom @LogHandler@ implementation that will be called for each line of log output generated by the Chat SDK. |
| 253 | + |
| 254 | +The @logLevel@ sets the verbosity of logs that will be output by the SDK. The following log levels are available to set: |
| 255 | + |
| 256 | +|_. Level |_. Description | |
| 257 | +| trace | Something routine and expected has occurred. This level will provide logs for the vast majority of operations and function calls. | |
| 258 | +| debug | Development information, messages that are useful when trying to debug library behavior, but superfluous to normal operation. | |
| 259 | +| info | Informational messages. Operationally significant to the library but not out of the ordinary. | |
| 260 | +| warn | Anything that is not immediately an error, but could cause unexpected behavior in the future. For example, passing an invalid value to an option. Indicates that some action should be taken to prevent future errors. | |
| 261 | +| error | A given operation has failed and cannot be automatically recovered. The error may threaten the continuity of operation. | |
| 262 | +| silent | No logging will be performed. | |
0 commit comments