pubnub-angular2

Welcome! We're here to get you started quickly with your integration between PubNub and Angular2. PubNub makes it easy to integrate real-time bidirectional communication into your app.

Pubnub Angular2 service is a wrapper for PubNub JavaScript SDK version 4 that adds a few of extra features to simplify Angular integrations:

You can still use the native PubNub JavaScript SDK if you feel this will be more suitable for your situation.

Communication

• If you need help or have a general question, contact support@pubnub.com
• If you want to contribute, please open a pull request against the develop branch.

Integrating PubNub Angular SDK into Your App

Your HTML page will include 2 key libraries:

• PubNub JavaScript SDK V4

  • With NPM:

    npm install pubnub

  • With Bower:

    bower install pubnub

• PubNub JavaScript SDK Angular2 Service

  • With NPM:

    npm install pubnub-angular2

  • With Bower:

    bower install pubnub-angular2

  • From CDN:

    <script src="http(s)://cdn.pubnub.com/sdk/pubnub-angular2/pubnub-angular2.(version).js"></script>
    <script src="http(s)://cdn.pubnub.com/sdk/pubnub-angular2/pubnub-angular2.(version).min.js"></script>

To utilize this wrapper, include the scripts in the following order:

  <script src="(latest version of PubNub JS SDK from https://github.com/pubnub/javascript)"></script>
  <script src="(pubnub-angular2.js)"></script>

You have to register PubNubAngular inside providers property either in yours ngModule or ngComponent, this is going to depend on how far do you want to get your Pubnub instance.

This will make sure that the Pubnub object is available to get injected into your ngComponents, Pubnub is going to be defined inside your ngModule, it allows that PubNubAngular is accessible globally.

(function (app) {

    app.your_module = ng.core.NgModule({
        imports: [...],
        declarations: [...],
        providers: [window.PubNubAngular],
        bootstrap: [...]
    }).Class({
        constructor: function(){}
    });

    document.addEventListener('DOMContentLoaded', function(){
        ng.platformBrowserDynamic.platformBrowserDynamic().bootstrapModule(app.your_module);
    });

})(window.app || (window.app = {}));

How to inject pubnub service inside the angular component.

If it was not used ngModule to register PubNub like above, this there has to register directly from ngComponent.

(function (app) {

    app.main_component = ng.core.Component({

        selector: '...',
        templateUrl: '...'

    }).Class({

        constructor: [window.PubNubAngular, function(pubnubService){

            pubnubService.init({
                publishKey: 'your pub key',
                subscribeKey: 'your sub key'
            });

            ...
        }]
    });

})(window.app || (window.app = {}));

Differences in usage with native JavaScript SDK

In Pubnub Angular2 SDK instances are hidden inside service and are accessible via instance getter.

Creating a default instance PubNub JS V4

var defaultInstance = new PubNub({
    publishKey: 'your pub key',
    subscribeKey: 'your sub key'
});

Creating a default instance PubNub Angular 2 SDK

var pubnubService = new window.PubNubAngular();

pubnubService.init({
    publishKey: 'your pub key',
    subscribeKey: 'your sub key'
});

Creating an other instance

In most use cases, usage of the default PubNub instance will be sufficient, but if multiple instances with different credentials are needed, the pubnubService.getInstance(instanceName) getter needs to be utilized.

var pubnubService = new window.PubNubAngular();

pubnubService.getInstance("another").init({
	publishKey: 'your pub key',
	subscribeKey: 'your sub key'
});

Accessing methods

All methods of the Native Javascript SDKs are wrapped within the Pubnub Angular2 SDK.

• Methods of default instance are mapped directly to PubNub service like pubnubService.publish({...}).
• Methods of the other instances are available via the instance getter like pubnubService.getInstance(instanceName).publish().

To learn about PubNub JavaScript features and methods available refer to the API Reference of the Javascript SDK that you are using:

• JavaScript V4 API Reference

Examples:

pubnubService.publish({channel: 'myChannel', message: 'Hello!'}, (status, response) => {
    console.log(response);
});

With an other instance

pubnubService.getInstance("another").publish({channel: 'myChannel', message: 'Hello!'}, (status, response) => {
    console.log(response);
});

That's it - you're ready to start using the Angular2 PubNub SDK!

Events

Another key feature of this SDK is the ability to trigger method events in addition to passed in callbacks. By default events will not be triggered.

To enable all possible events for certain method, add triggerEvents: true option to the method arguments.

pubnubService.subscribe({channels: ['myChannel1'], triggerEvents: true, withPresence: true});

To enable specific triggerEvents, add triggerEvents: ['message', 'presence', 'status']option to the method arguments.

pubnubService.subscribe({channels: ['myChannel1'], triggerEvents: ['message', 'status']});

To get that presence event works, do not forget to add withPresence: true

Triggering and listening to events for the subscribe method

For listening trigger events is available broadcastOn this allows to intercept events using a callback per channel or callback per a set of channels.

With Javascript V4, you can trigger 3 different events (message, presence and status)

Pubnub.subscribe({
    channels  : ['myChannel1', 'myChannel2', 'myChannel3'],
    channelGroups: ['myGroup1', 'myGroup2'],
    withPresence: true,
    triggerEvents: ['message', 'presence', 'status']
  });
};

You can also enable all possible events using triggerEvents: true

Listening to a message event of a specific channel or channel group:

pubnubService.getMessage('myChannel', (msg) => {
    console.log(msg);
});

pubnubService.getMessage('myGroup1', (msg) => {
    console.log(msg);
});

Listening to a message event of a specific set of channels or channel groups:

pubnubService.getMessage(['myChannel1', 'myChannel2', 'myGroup1'], (msg) => {
    console.log(msg.message);
    console.log(msg.channel);
});

Listening to a presence event of a specific channel or channel group:

pubnubService.getPresence('myChannel', (pse) => {
    console.log(pse);
});

pubnubService.getPresence('myGroup1', (pse) => {
    console.log(pse);
});

Listening to a presence event of a specific set of channels or channel groups:

pubnubService.getPresence(['myChannel1', 'myChannel2', 'myGroup1'], (pse) => {
    console.log(pse);
    console.log(pse.subscribedChannel);
});

Listening to the global status for a channel or channel group:

pubnubService.getStatus('myChannel', (st) => {
    console.log(st);
});

pubnubService.getStatus('myGroup1', (st) => {
    console.log(st);
});

Listening to the global status for a specific set of channels or channel group:

pubnubService.getStatus(['myChannel1', 'myChannel2', 'myGroup1'], (st) => {
    console.log(st);
});

Catching trigger errors

pubnubService.getError((err) => {
    console.log(err);
});