Repository navigation
Update README for 2.0 #613
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,122 +1,161 @@ | ||
|  | ||
| [](https://pub.dev/packages/ably_pubsub_device_flutter) | ||
| [](https://github.com/ably/ably-pubsub-flutter/blob/main/LICENSE) | ||
|  | ||
|
|
||
| --- | ||
| [](https://pub.dev/packages/ably_pubsub_device_flutter) | ||
| [](https://github.com/ably/ably-pubsub-flutter/blob/main/LICENSE) | ||
|
|
||
| # Ably Pub/Sub Flutter SDK | ||
|
|
||
| Build any realtime experience using Ably’s Pub/Sub Flutter SDK. Supported on popular platforms and frameworks, including Android and iOS. | ||
| The Flutter SDK for [Ably Pub/Sub](https://ably.com/docs/basics): publish and subscribe to | ||
| channels, and use message history, presence and push notifications, from Android and iOS apps. | ||
|
|
||
| Ably Pub/Sub provides flexible APIs that deliver features such as pub-sub messaging, message history, presence, and push notifications. Utilizing Ably’s realtime messaging platform, applications benefit from its highly performant, reliable, and scalable infrastructure. | ||
| ## Overview | ||
|
|
||
| Find out more: | ||
| This SDK provides the device package only, for end-user apps. There is no server package; for | ||
| backends, use a server SDK such as [JavaScript](https://github.com/ably/ably-pubsub-js), | ||
| [Java](https://github.com/ably/ably-pubsub-java), [Go](https://github.com/ably/ably-pubsub-go), | ||
| [.NET](https://github.com/ably/ably-pubsub-dotnet), [Python](https://github.com/ably/ably-pubsub-python), | ||
| [PHP](https://github.com/ably/ably-pubsub-php) or [Ruby](https://github.com/ably/ably-pubsub-ruby). | ||
|
|
||
| * [Ably Pub/Sub docs.](https://ably.com/docs/basics) | ||
| * [Ably Pub/Sub examples.](https://ably.com/examples?product=pubsub) | ||
| | Package | Use it for | Entry point | | ||
| |---------|------------|-------------| | ||
| | [`ably_pubsub_device_flutter`](https://pub.dev/packages/ably_pubsub_device_flutter) | Applications on end-user devices | `createClient` | | ||
|
|
||
| --- | ||
| ## Requirements | ||
|
|
||
| ## Getting started | ||
| Flutter 3.44 or later, with Dart 3.12 or later. Apps run on Android 7.0 (API level 24) or later | ||
| and iOS 15 or later, and iOS builds need Xcode 26 or later. | ||
|
|
||
| Everything you need to get started with Ably: | ||
| ## Installation | ||
|
|
||
| * [Getting started in Pub/Sub using Flutter.](https://ably.com/docs/getting-started/flutter) | ||
| * [SDK Setup for Flutter.](https://ably.com/docs/getting-started/setup?lang=flutter) | ||
| ```bash | ||
| flutter pub add ably_pubsub_device_flutter | ||
| ``` | ||
|
|
||
| --- | ||
| ### iOS setup | ||
|
|
||
| ## Supported platforms | ||
| The plugin is a Swift package that needs iOS 15, but `flutter create` targets iOS 13. In Xcode, open | ||
| `ios/Runner.xcworkspace` and set **Runner > General > Minimum Deployments** to 15.0 or later. | ||
| Swift Package Manager is on by default from Flutter 3.44; if your app turns it off, see | ||
| [UPDATING.md](https://github.com/ably/ably-pubsub-flutter/blob/main/UPDATING.md#upgrading-from-v12x). | ||
|
|
||
| Ably aims to support a wide range of platforms. If you experience any compatibility issues, open an issue in the repository or contact [Ably support](https://ably.com/support). | ||
| ## Quick start | ||
|
|
||
| This SDK supports the following platforms: | ||
| Authenticate a device with tokens issued by your own server, through `authUrl` or `authCallback`. | ||
| Never embed an API key in an app that runs on an end-user device. | ||
|
|
||
| | Platform | Support | | ||
| |----------|---------| | ||
| | Android | Android 7.0 (API level 24) or newer | | ||
| | iOS | iOS 15 or newer | | ||
| | Flutter | Flutter 3.44.0 or higher | | ||
| ```dart | ||
| import 'package:ably_pubsub_device_flutter/ably_pubsub_device_flutter.dart' as ably; | ||
| import 'package:flutter/widgets.dart'; | ||
|
|
||
| You might also need to upgrade [gradle distribution](https://developer.android.com/studio/releases/gradle-plugin#updating-plugin). | ||
| > [!IMPORTANT] | ||
| > SDK versions < 1.2.25 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025. | ||
| Future<void> main() async { | ||
| WidgetsFlutterBinding.ensureInitialized(); | ||
|
|
||
| --- | ||
| final client = ably.createClient( | ||
| options: ably.ClientOptions( | ||
| authUrl: 'https://your-server.example.com/ably-auth', | ||
| clientId: 'me', | ||
| ), | ||
| ); | ||
|
|
||
| ## Installation | ||
| // The client connects automatically. Subscribing attaches the channel. | ||
| final channel = client.channels.get('test-channel'); | ||
| channel.subscribe().listen((ably.Message message) { | ||
| print('Received: ${message.data}'); | ||
| }); | ||
|
|
||
| To get started with your project, install the package: | ||
| await channel.publish(name: 'test-event', data: 'hello world'); | ||
| } | ||
| ``` | ||
|
|
||
| Add the Ably Flutter package to your project by including it in your `pubspec.yaml` file: | ||
| To get tokens from your own code instead of a URL, set `authCallback`. It can return a token | ||
| string, a `TokenDetails` or a `TokenRequest`. | ||
|
|
||
| ```yaml | ||
| dependencies: | ||
| ably_pubsub_device_flutter: ^2.0.0 | ||
| ``` | ||
| ## Migrating from 1.x | ||
|
|
||
| Version 2.0 renames the package and creates clients with `createClient`. | ||
|
|
||
| | | 1.x | 2.0 | | ||
| |---|---|---| | ||
| | Package | `ably_flutter` | `ably_pubsub_device_flutter` | | ||
| | Import | `package:ably_flutter/ably_flutter.dart` | `package:ably_pubsub_device_flutter/ably_pubsub_device_flutter.dart` | | ||
| | Realtime client | `ably.Realtime(options: ...)` | `ably.createClient(options: ...)` | | ||
| | REST client | `ably.Rest(options: ...)` | Removed | | ||
|
|
||
| See [UPDATING.md](https://github.com/ably/ably-pubsub-flutter/blob/main/UPDATING.md#upgrading-from-v12x) for all other changes. | ||
|
|
||
| Once added to your dependencies, import it in your Dart code: | ||
| ## Common configuration | ||
|
|
||
| ### Endpoint | ||
|
|
||
| `endpoint` selects the Ably host for HTTP requests and the realtime connection. It replaces | ||
| the 1.x `environment`, `restHost` and `realtimeHost` options. | ||
|
|
||
| ```dart | ||
| import 'package:ably_pubsub_device_flutter/ably_pubsub_device_flutter.dart' as ably; | ||
| final client = ably.createClient( | ||
| options: ably.ClientOptions( | ||
| authUrl: 'https://your-server.example.com/ably-auth', | ||
| clientId: 'me', | ||
| endpoint: 'nonprod:sandbox', | ||
| ), | ||
| ); | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > When increasing the version of `ably_pubsub_device_flutter` in your `pubspec.yaml`, if there are breaking changes, follow the [updating / migration guide](UPDATING.md). | ||
| - Never put a port in `endpoint`: `localhost:8080` is not a hostname and does not resolve. | ||
| - Set the port with `tlsPort`, or with `port` when TLS is off. | ||
| - With TLS off (`tls: false`), use token authentication. | ||
|
|
||
| --- | ||
| See [UPDATING.md](https://github.com/ably/ably-pubsub-flutter/blob/main/UPDATING.md#upgrading-from-v12x) for how the old options map to `endpoint`. | ||
|
|
||
| ## Usage | ||
| ### Logging | ||
|
|
||
| The following code connects to Ably's realtime messaging service, subscribes to a channel to receive messages, and publishes a test message to that same channel: | ||
| Set `logLevel` to a `LogLevel` value: `none`, `verbose`, `debug`, `info`, `warn` or `error`. The | ||
| default is `info`. The native SDK writes the log output; there is no log handler option. | ||
|
|
||
| ```dart | ||
| // Initialize Ably Pub/Sub client | ||
| final clientOptions = ably.ClientOptions( | ||
| key: 'your-ably-api-key', | ||
| final client = ably.createClient( | ||
| options: ably.ClientOptions( | ||
| authUrl: 'https://your-server.example.com/ably-auth', | ||
| clientId: 'me', | ||
| ); | ||
|
|
||
| final pubSubClient = ably.createClient(options: clientOptions); | ||
|
|
||
| // Wait for connection to be established | ||
| await pubSubClient.connection | ||
| .on(ably.ConnectionEvent.connected) | ||
| .first | ||
| .then((stateChange) { | ||
| print('Connected to Ably'); | ||
| }); | ||
|
|
||
| // Get a reference to the 'test-channel' channel | ||
| final channel = pubSubClient.channels.get('test-channel'); | ||
|
|
||
| // Subscribe to all messages published to this channel | ||
| channel.subscribe().listen((ably.Message message) { | ||
| print('Received message: ${message.data}'); | ||
| }); | ||
|
|
||
| // Publish a test message to the channel | ||
| await channel.publish( | ||
| name: 'test-event', | ||
| data: 'hello world', | ||
| ); | ||
| logLevel: ably.LogLevel.debug, | ||
| ), | ||
| ); | ||
| ``` | ||
|
|
||
| --- | ||
| ## Platform notes | ||
|
|
||
| ### Push notifications | ||
|
|
||
| The SDK can activate a device for push notifications and subscribe it to channels. Push works on: | ||
|
|
||
| - Android devices, and Android emulators with Google APIs | ||
| - Physical iOS devices, but not the iOS Simulator | ||
|
|
||
| ## Releases | ||
| See [PushNotifications.md](https://github.com/ably/ably-pubsub-flutter/blob/main/PushNotifications.md) for setup, sending and receiving. | ||
|
|
||
| The [CHANGELOG.md](./CHANGELOG.md) contains details of the latest releases for this SDK. You can also view all Ably releases on [changelog.ably.com](https://changelog.ably.com). | ||
| ## Known limitations | ||
|
|
||
| --- | ||
| - The Push Admin API is not available. The push APIs manage the current device only. See | ||
| [Known Limitations](https://github.com/ably/ably-pubsub-flutter/blob/main/PushNotifications.md#known-limitations) in PushNotifications.md. | ||
|
|
||
| ## Further reading | ||
|
|
||
| - [Getting started with Pub/Sub using Flutter](https://ably.com/docs/getting-started/flutter) | ||
| - [Ably Pub/Sub documentation](https://ably.com/docs/basics) and [examples](https://ably.com/examples?product=pubsub) | ||
| - [UPDATING.md](https://github.com/ably/ably-pubsub-flutter/blob/main/UPDATING.md): migrating from 1.x | ||
| - [CHANGELOG.md](https://github.com/ably/ably-pubsub-flutter/blob/main/CHANGELOG.md): release notes; all Ably releases are listed on [changelog.ably.com](https://changelog.ably.com) | ||
| - [PushNotifications.md](https://github.com/ably/ably-pubsub-flutter/blob/main/PushNotifications.md): push notifications on Android and iOS | ||
| - [example/](https://github.com/ably/ably-pubsub-flutter/tree/main/example): an example app | ||
|
|
||
| ## Contributing | ||
|
|
||
| Read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines to contribute to Ably. | ||
| Read [CONTRIBUTING.md](https://github.com/ably/ably-pubsub-flutter/blob/main/CONTRIBUTING.md) before contributing; it also describes the release | ||
| process. | ||
|
|
||
| ## Support, feedback and troubleshooting | ||
|
|
||
| --- | ||
| For help, visit Ably's [support page](https://ably.com/support). Report bugs and compatibility | ||
| problems on [GitHub Issues](https://github.com/ably/ably-pubsub-flutter/issues). | ||
|
|
||
| ## Support, feedback, and troubleshooting | ||
| ## License | ||
|
|
||
| For help or technical support, visit the [Ably Support page](https://ably.com/support) or [GitHub Issues](https://github.com/ably/ably-pubsub-flutter/issues) for community-reported bugs and discussions. | ||
| Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/ably/ably-pubsub-flutter/blob/main/LICENSE). | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.