flutter_pubnub 0.5.0

A cross platform plugin for creating real time messaging applications with PubNub

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.2.0 had a bug related to missing proguard rules, causing crashes when the library was initialized.

Easy setup

import 'package:flutter_pubnub/pubnub.dart';


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

copied to clipboard

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});

copied to clipboard

Table of contents

• Creating one or more clients
• Subscribe to channels and unsubscribe from channels
• Publishing to channels
• Handle presence
• Subscribe to PubNub events
• Channel Groups
• Retrieve history
• Push Notifications
• Signals
• Cleanup

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'));

copied to clipboard

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'));

copied to clipboard

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'));

copied to clipboard

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));

copied to clipboard

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"'));

copied to clipboard

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'
                }
              );

copied to clipboard

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'));

copied to clipboard

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();

copied to clipboard

Publishing to channels

A client can publish messages to one or many channels

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

copied to clipboard

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'
                }
              );

copied to clipboard

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'});

copied to clipboard

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'));

copied to clipboard

Channel Groups

Channel groups access are handled by the PubNub Access Manager.

Adding channels to a channel group

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

copied to clipboard

List channels belonging to a channel group

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

copied to clipboard

Remove channels from a channel group

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

copied to clipboard

Delete a channel group

_client.deleteChannelGroup('Group1');

copied to clipboard

Subscribe to channel groups

_client.subscribeToChannelGroups(['Group1']);

copied to clipboard

Unsubscribe from channel groups

_client.unsubscribeFromChannelGroups(['Group1']);

copied to clipboard

Retrieve history

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

copied to clipboard

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']);
    });
},

copied to clipboard

Listing channels enrolled in push notifications.

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

copied to clipboard

Removing channels from push notifications.

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

copied to clipboard

Removing all channels from push notifications.

_client.removeAllPushNotificationsFromDeviceWithPushToken(PushType.FCM, token);

copied to clipboard

Signals

Signals allow to send small payloads (30 bytes max) in a very efficient and cost effective way.

_client.signal(['Channel2'], {'signal': 'Hello Signal'});

copied to clipboard

Cleanup

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

_client.dispose();

copied to clipboard

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