flutter_pubnub 0.5.0

Flutter Android iOS

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

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

Channel Groups #

Channel groups access are handled by the PubNub Access Manager.

Adding channels to a channel group #


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

Signals #

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


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

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

8
likes
100
pub points
72%
popularity

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

Repository (GitHub)
View/report issues

Documentation

API reference

Uploader

obrand69@gmail.com

License

Apache 2.0 (LICENSE)

Dependencies

flutter, uuid

More

Packages that depend on flutter_pubnub