flutter_pubnub 0.1.4

  • Readme
  • Changelog
  • Example
  • Installing
  • new70

Flutter PubNub Plugin #

A cross platform plugin for implementing real time messaging applications using PubNub (https://www.pubnub.com/). This plugin is not provided nor supported by PubNub. It was implemented part of a real time messaging application developed by Ingenio (https://www.ingenio.com/).

Features #

  • Multi client support allowing to handle messaging and presence from multiple PubNub clients defined in the PubNub environment.
  • Auth key handling
  • Filter expression handling
  • Presence capabilities
  • Publish and Subscribe/Unsubscribe capabilities
  • Channel Groups
  • History
  • Push notifications
  • Status
  • Error handling

IMPORTANT NOTES:

  • The plugin can only be used on iOS and Android and not supported on Flutter Web. In order to support Web, Desktop and mobile platforms, PubNub would have to create a pure Dart plugin that directly accesses their low level REST API.

Roadmap #

The plugin does not cover all functionalities offered by PubNub but is functional for implementing already complex real time messaging apps on iOS and Android. We have items we will be working on soon:

PNConfig features:

  • cipher key
  • custom origin

Getting Started #

The plugin follows as much as possible the naming conventions PubNub exposes via their respective iOS and Android SDK.

Note: version 0.1.2 has breaking changes. unsubscribe, presence and publish methods are now accepting an array of channels rather than just one channel.

Easy setup #

import 'package:flutter_pubnub/pubnub.dart';


final PubNub _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx'));

The PubNubConfig constructor allows to pass a PubNub auth key, presence timeout in seconds, a filter expression and finally a UUID (note a default UUID is generated if not provided)


PubNubConfig(this.publishKey, this.subscribeKey, {this.authKey, this.presenceTimeout, this.uuid, this.filter});

Table of contents #

Creating one or more clients #

Creating one or more clients with PubNub subscribe and publish keys


// Note that the proper key values for PubNub are found in the client configuration dashboard under your PubNub account
final PubNub _client1 = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx'));
final PubNub _client2 = PubNub(PubNubConfig('pub-c-yyyy', 'sub-cyyy'));

Creating a client with a PubNub auth key


// Note that the proper key values for PubNub are found in the client configuration dashboard under your PubNub account
final PubNub _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', authKey: 'auth-xxxx'));

Creating a client with a UUID


// Note that the proper key values for PubNub are found in the client configuration dashboard under your PubNub account
final PubNub _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', uuid: '127c1ab5-fc7f-4c46-8460-3207b6782007'));

Creating a client with a presence timeout in seconds


// Note that the proper key values for PubNub are found in the client configuration dashboard under your PubNub account
final PubNub _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', presenceTimeout: 120));

Creating a client with a filter expression


// The filter expression here is done, as an example on the uuid, so any messages sent from the client with that UUID will not be received in the subscribe method
final PubNub _client = PubNub(PubNubConfig('pub-c-xxxx', 'sub-cxxx', filter: 'uuid != "127c1ab5-fc7f-4c46-8460-3207b6782007"'));

Then in order to publish a message with the proper metadata that will trigger the filtering


// The filter expression here is done, as an example on the uuid, so any messages sent from the client with that UUID will not be received in the subscribe method
_client.publish(['Test-Channel1'], {'message': 'Hello World'},
               metadata: {
                'uuid': '127c1ab5-fc7f-4c46-8460-3207b6782007'
                }
              );

Retrieve the client UUID #

In some cases, especially when the UUID is not setup during client creation, it can be helpful getting the UUID that was automatically generated by PubNub.


_client.uuid().then((uuid) => print('UUID: $uuid'));

Subscribe to channels and unsubscribe from channels #

A client can subscribe to one or many channels. It can also unsubscribe from one or many/all channels


 _client.subscribe(['Test-Channel1', 'Test-Channel1']);

 _client.unsubscribe(['Test-Channel1']);
 
 _client.unsubscribeAll();

Publishing to channels #

A client can publish messages to one or many channels


 _client.publish((['Test-Channel1'], {'message': 'Hello World!'});

As previously described, if a filter has been set and if we need to react to it, metadata related to the configured filter must be passed during publication.


_client.publish(['Test-Channel1'], {'message': 'Hello World'},
               metadata: {
                'uuid': '127c1ab5-fc7f-4c46-8460-3207b6782007'
                }
              );

Handle presence #

A client can respond to presence events generated by PubNub (client disconnection, ...) but can also send custom presence events to one or many channels.


_client.presence(['Test-Channel1'], {'state': 'busy'});

Subscribe to PubNub events #

In order to build a chat service for example, the client does not only send messages but must also consume messages, be aware if the client on the other end disconnected, status.


_client.onStatusReceived.listen((status) => print('Status:${status.toString()}'));

_client.onPresenceReceived.listen((presence) => print('Presence:${presence.toString()}'));

_client.onMessageReceived.listen((message) => print('Message:$message'));

_client.onErrorReceived.listen((error) => print('Error:$error'));

Adding channels to a channel group #

Channel groups access are handled by the PubNub Access Manager.


_client.addChannelsToChannelGroup('Group1', ['Channel', 'Channel2']);

List channels belonging to a channel group #


_client.listChannelsForChannelGroup('Group1').then((channels) {
                          print("Channels in Group 1: $channels");
                        });
                        

Remove channels from a channel group #


 _client.removeChannelsFromChannelGroup('Group1', ['Channel']);
                        

Delete a channel group #


_client.deleteChannelGroup('Group1');

Subscribe to channel groups #


_client.subscribeToChannelGroups(['Group1']);

Unsubscribe from channel groups #


_client.unsubscribeFromChannelGroups(['Group1']);

Retrieve history #


_client.history('Channel', 1).then((items) {
                          if (items != null && items.isNotEmpty) {
                            print("Last Item: $items");
                          } else {
                            print('No items');
                          }
                        });
                        

Push Notifications #

Adding channels for push notifications using a Firebase messaging plugin push token


_firebaseMessaging.getToken().then((token) {
    print("Token: $token");
    _client.addPushNotificationsOnChannels(PushType.FCM, token, ['Channel']);
    });
},

Listing channels enrolled in push notifications.


_client.listPushNotificationChannels(PushType.FCM, token).then((channels) {
    print("Push Notes Channels: $channels");
});

Removing channels from push notifications.


_client.removePushNotificationsFromChannels(PushType.FCM, token, ['Channel']);

Removing all channels from push notifications.


_client.removeAllPushNotificationsFromDeviceWithPushToken(PushType.FCM, token);

Cleanup #

When done with a PubNub client, the client can be closed and cleaned up.


_client.dispose();

License #

This plugin is under an Apache 2.0 license

Features and bugs #

Please file feature requests and bugs at the issue tracker. https://github.com/Ingenio/flutter_pubnub/issues

[0.0.1]

  • Android and iOS PubNub Flutter plugin. Implements subscribe, unsubscribe, publish, status, filter expressions, presence and error handling. Also allows multiple PubNub clients to be created.

[0.1.0]

  • Refactored code so spread operators are not used

[0.1.1]

  • Documentation tweaks

[0.1.2]

  • Breaking changes: Now publish, presence and unsubscribe take an array of channels

[0.1.3]

  • Removed unused constant and documentation tweaks

[0.1.4]

  • Added channel groups handling, push notifications and history

example/README.md

flutter_pubnub_example #

Demonstrates how to use the flutter_pubnub plugin.

Getting Started #

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

For help getting started with Flutter, view our online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  flutter_pubnub: ^0.1.4

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:flutter_pubnub/generated/i18n.dart';
import 'package:flutter_pubnub/pubnub.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
40
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
70
Learn more about scoring.

We analyzed this package on Oct 11, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21
  • Flutter: 1.9.1+hotfix.4

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
uuid ^2.0.2 2.0.2
Transitive dependencies
charcode 1.1.2
collection 1.14.11 1.14.12
convert 2.1.1
crypto 2.1.3
meta 1.1.7
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test