Angular2PubNub Angular2 V4 SDK 1.3.0

npm install --save pubnub pubnub-angular2
bower install --save pubnub pubnub-angular2

PubNub Angular2 is wrapper for PubNub Javascript SDK v4 that adds a few extra features to simplify the integration to Angular v2 and v4.

  • Support: Available to use with Typescript or Javascript plain.
  • Events: Delegate methods accept the triggerEvents option which will broadcast certain callback and binding these directly to the HTML.
  • Autoload: An easy and fast way to recovery the history messages of your channel.
  • Multiple instance behavior: All instance are accessible throughout application via PubNub service.

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

npm install --save pubnub pubnub-angular2

You have to two ways for registering PubNubAngular in your list of providers in your Angular App and these are in: ngModules or ngComponents.

Angular Module lets you to use the same instance of PubNub in all Angular Components declared in this. Then you will not need to register PubNub in any Angular Component hosted by the Angular Module.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { PubNubAngular } from 'pubnub-angular2';
import { AppComponent } from './appComponent';
@NgModule({
    imports:[ BrowserModule ],
    declarations:[ AppComponent ],
    providers:[ PubNubAngular ],
    bootstrap:[ AppComponent ]
})
export class AppModule {
    constructor() {}
}

Angular Component only lets to use the same instance of PubNub inside itself and its Angular Components children. For more information about this we recommend to visit Depedency Injection and Hierarchical Dependency Injectors.

import { Component } from '@angular/core';
import { PubNubAngular } from 'pubnub-angular2';
@Component({
    selector: 'appComponent',
    template: '<H1>PubNub Angular2 SDK Demo</H1>',
    providers:[ PubNubAngular ]
})
export class AppComponent {
    constructor() {}
}

Now you can inject PubNubAngular in your ngComponents

import { Component } from '@angular/core';
import { PubNubAngular } from 'pubnub-angular2';
@Component({
    selector: 'appComponent',
    template: '<H1>PubNub Angular2 SDK Demo</H1>'
})
export class AppComponent {
    constructor(pubnub: PubNubAngular) {
    pubnub.init({
        publishKey: 'YOUR PUB_KEY',
        subscribeKey: 'YOUR SUB_KEY'
        });
    }
}

For Angular2 you have to add some extra steps in order to setup the environment, Your HTML page will have to include the next libraries.

  • Global dependencies for Angular2
  • Angular2
  • PubNub Javascript SDK
  • PubNub Angular2 SDK

With Javascript is possible to use the libraries from CDN, NPM and Bower.

  1. Include global dependencies for Angular2:
     
                <script src="node_modules/core-js/client/shim.min.js"></script>
                <script src="node_modules/zone.js/dist/zone.js"></script>
                <script src="node_modules/reflect-metadata/Reflect.js"></script>
                <script src="node_modules/rxjs/bundles/Rx.js"></script>
            
  2. Include Angular2
                <script src="node_modules/@angular/core/bundles/core.umd.js"></script>
                <script src="node_modules/@angular/common/bundles/common.umd.js"></script>
                <script src="node_modules/@angular/compiler/bundles/compiler.umd.js"></script>
                <script src="node_modules/@angular/platform-browser/bundles/platform-browser.umd.js"></script>
                <script src="node_modules/@angular/forms/bundles/forms.umd.js"></script>
                <script src="node_modules/@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js"></script>
            
  3. Include the lastest version of PubNub's Javascript SDK:
     
                    <script src="node_modules/pubnub/dist/web/pubnub.js"></script>
            
  4. Include PubNub's Angular2 SDK:
     
                    <script src="node_modules/pubnub-angular2/dist/pubnub-angular2.js"></script>
            

Your HTML page will have to include the same libraries described above but you have to load the Angular2 and PubNub Angular2 SDK from NPM modules.

  1. Include global dependencies for Angular2:
     
                <script src="node_modules/core-js/client/shim.min.js"></script>
                <script src="node_modules/zone.js/dist/zone.js"></script>
                <script src="node_modules/reflect-metadata/Reflect.js"></script>
                <script src="node_modules/rxjs/bundles/Rx.js"></script>
            
  2. Include the lastest version of PubNub's Javascript SDK:
     
                    <script src="node_modules/pubnub/dist/web/pubnub.js"></script>
            
  3. Include and load libraries from systemjs:
     
                <script src="node_modules/systemjs/dist/system.src.js"></script>
                <script src="systemjs.config.js"></script>
                <script>
                    System.import('app').catch(function(err){ 
                        console.error(err);
                    });
                </script>
            

Angular2 uses systemjs.config.js and this will have to include next libraries inside the map attribute.

  • Rxjs
  • Angular2
  • PubNub Angular2 SDK
    map: {
        'rxjs': 'npm:rxjs',
        '@angular/core': 'npm:@angular/core/bundles/core.umd.js',
        '@angular/common': 'npm:@angular/common/bundles/common.umd.js',
        '@angular/compiler': 'npm:@angular/compiler/bundles/compiler.umd.js',
        '@angular/platform-browser': 'npm:@angular/platform-browser/bundles/platform-browser.umd.js',
        '@angular/platform-browser-dynamic': 'npm:@angular/platform-browser-dynamic/bundles/platform-browser-dynamic.umd.js',
        '@angular/http': 'npm:@angular/http/bundles/http.umd.js',
        '@angular/router': 'npm:@angular/router/bundles/router.umd.js',
        '@angular/forms': 'npm:@angular/forms/bundles/forms.umd.js',
        'pubnub-angular2': 'npm:pubnub-angular2/dist/pubnub-angular2.js'
    }
    

You have to two ways for registering PubNub Angular2 SDK in your list of providers in your Angular App and these are in: Angular Modules or Components.

Angular Module lets you to use the same instance of PubNub in all Angular Components declared in this. Then you will not need to register PubNub in any Angular Component hosted by the Angular Module.

    'use strict';

    (function (app) {
        app.appModule = ng.core.NgModule({
            imports: [ng.platformBrowser.BrowserModule],
            declarations: [app.appComponent],
            providers: [ PubNubAngular ],
            bootstrap: [app.appComponent]
        }).Class({
            constructor: function(){}
        });

        document.addEventListener('DOMContentLoaded', function(){
            ng.platformBrowserDynamic.platformBrowserDynamic().bootstrapModule(app.appModule);
        });
    })(window.app || (window.app = {}));
    
    import { NgModule } from '@angular/core';
    import { BrowserModule } from '@angular/platform-browser';
    import { PubNubAngular } from 'pubnub-angular2';
    import { AppComponent } from './appComponent';
    @NgModule({
        imports:[ BrowserModule ],
        declarations:[ AppComponent ],
        providers:[ PubNubAngular ],
        bootstrap:[ AppComponent ]
    })
    export class AppModule {
        constructor() {}
    }
    

Angular Component only lets to use the same instance of PubNub inside itself and its Angular Components children. For more information about this we recommend to visit Dependency Injection and Hierarchical Dependency Injectors

    (function (app) {
        app.appComponent = ng.core.Component({
            selector: 'appComponent',
            template: '<H1>PubNub Angular2 SDK Demo</H1>'
            providers: [ PubNubAngular ]
        }).Class({
            constructor: function () {}
        });
    })(window.app || (window.app = {}));
    
    import { Component } from '@angular/core';
    import { PubNubAngular } from 'pubnub-angular2';
    @Component({
        selector: 'appComponent',
        template: '<H1>PubNub Angular2 SDK Demo</H1>',
        providers: [PubNubAngular]
    })
    export class AppComponent {
        constructor() {}
    }
    

Registering PubNubAngular within the provider list in an Angular Module or Component lets to inject an instance the PubNub in an Angular Component according to the Hierarchical Dependency, then this will be a shared instance.

After injecting the PubNub instance in the Angular Component's constructor will have to initialize the service including the PUB_KEY and SUB_KEY. It is important to know that this process has to be done once because this instance will be shared by all Angular Components within same scope according to its dependency model choose.

    (function (app) {
        app.appComponent = ng.core.Component({
            selector: 'appComponent',
            template: '<H1>PubNub Angular2 SDK Demo</H1>'
        }).Class({
            constructor: [PubNubAngular, function(pubnub){
                pubnub.init({
                    publishKey: 'YOUR PUB_KEY',
                    subscribeKey: 'YOUR SUB_KEY'
                });
            }]
        });
    })(window.app || (window.app = {}));
    
    import { Component } from '@angular/core';
    import { PubNubAngular } from 'pubnub-angular2';
    @Component({
        selector: 'appComponent',
        template: '<H1>PubNub Angular2 SDK Demo</H1>'
    })
    export class AppComponent {
        constructor(pubnub: PubNubAngular) {
            pubnub.init({
                publishKey: 'YOUR PUB_KEY',
                subscribeKey: 'YOUR SUB_KEY'
            });
        }
    }
    

To learn about PubNub JavaScript features refer to native PubNub JavaScript SDK manual. All methods of this SDK are wrapped with PubNubAngular.

Native PubNub JavaScript SDK provides instance creation using Pubnub.init(), which returns new instance with given credentials. In PubNub Angular2 SDK instances are hidden inside service and are accessible via instance getter. Methods of default instance are mapped directly to PubNub service just like Pubnub.publish({...}). In most use cases usage of the only default PubNub instance will be enough, but if you need multiple instances with different credentials, you should use Pubnub.getInstance(instanceName) getter. In this case publish method will looks like Pubnub.getInstance(instanceName).publish({}).

    var defaultInstance = new PubNub({
        publishKey: 'YOUR PUB_KEY',
        subscribeKey: 'YOUR SUB_KEY'
    });

    var anotherInstance = new PubNub({
        publishKey: 'ANOTHER PUB_KEY',
        subscribeKey: 'ANOTHER SUB_KEY'
    });

    defaultInstance.publish(
        {
            message: {such: 'Hello!'},
            channel: 'my_channel'
        },
        function (status, response) {
            if (status.error) {
                console.log(status);
            } else {
                console.log("message Published w/ timetoken", response.timetoken);
            }
        }
    );

    anotherInstance.grant(
        {
            channels: ['my_channel'],
            authKeys: ['my_authkey'],
            read: true,
            write: false
        },
        function (status) {
            console.log(status);
        }
    );
    
    declare var PubNub: any;

    var defaultInstance = new PubNub({
        publishKey: 'YOUR PUB_KEY',
        subscribeKey: 'YOUR SUB_KEY'
    });

    var anotherInstance = new PubNub({
        publishKey: 'ANOTHER PUB_KEY',
        subscribeKey: 'ANOTHER SUB_KEY'
    });

    defaultInstance.publish(
        {
            message: {such: 'Hello!'},
            channel: 'my_channel'
        },
        (status, response) => {
            if (status.error) {
                console.log(status);
            } else {
                console.log('message Published w/ timetoken', response.timetoken);
            }
        }
    );

    anotherInstance.grant(
        {
            channels: ['my_channel'],
            authKeys: ['my_authkey'],
            read: true,
            write: false
        },
        (status) => {
            console.log(status);
        }
    );
    
    (function (app) {
        app.appComponent = ng.core.Component({
            selector: 'appComponent',
            template: '<H1>PubNub Angular2 SDK Demo</H1>'
        }).Class({
            constructor: [PubNubAngular, function(pubnub){
                pubnub.init({
                    publishKey: 'YOUR PUB_KEY',
                    subscribeKey: 'YOUR SUB_KEY'
                });

                pubnub.getInstance("another").init({
                    publishKey: 'ANOTHER PUB_KEY',
                    subscribeKey: 'ANOTHER SUB_KEY'
                });

                pubnub.publish(
                    {
                        message: {
                            such: 'Hello!'
                        },
                        channel: 'my_channel'
                    }, 
                    function (status, response) {
                        if (status.error) {
                            console.log(status);
                        } else {
                            console.log('message Published w/ timetoken', response.timetoken);
                        }
                    }
                );

                pubnub.getInstance('another').grant(
                    {
                        channels: ['my_channel'],
                        authKeys: ['my_authkey'],
                        read: true,
                        write: false
                    }, 
                    function (status) {
                        console.log(status);
                    }
                );
            }]
        });
    })(window.app || (window.app = {}));
    
    import { Component } from '@angular/core';
    import { PubNubAngular } from 'pubnub-angular2';

    @Component({
        selector: 'appComponent',
        template: '<H1>PubNub Angular2 SDK Demo</H1>'
    })

    export class AppComponent {
        constructor(pubnub: PubNubAngular) {
            pubnub.init({
                publishKey: 'YOUR PUB_KEY',
                subscribeKey: 'YOUR SUB_KEY'
            });

            pubnub.getInstance('another').init({
                publishKey: 'ANOTHER PUB_KEY',
                subscribeKey: 'ANOTHER SUB_KEY'
            });

            pubnub.publish(
                {
                    message: {such: 'Hello!'},
                    channel: 'my_channel'
                },
                (status, response) => {
                    if (status.error) {
                        console.log(status);
                    } else {
                        console.log('message Published w/ timetoken', response.timetoken);
                    }
                }
            );

            pubnub.getInstance("another").grant(
                {
                    channels: ['my_channel'],
                    authKeys: ['my_authkey'],
                    read: true,
                    write: false
                }, (status) => {
                    console.log(status);
                }
            );
        }
    }
    

That's it, you are ready to start using PubNubAngular SDK.

(function (app) {
    app.main_component = ng.core.Component({
        selector: 'appComponent',
        template: "<ul>" +
        "<li *ngFor='let item of PubNub.getMessage(channel)'>{{item.message}}</li>" +
        "</ul>"
    }).Class({
        constructor: [PubNubAngular, function(pubnub) {
            this.channel = 'my_channel';
            this.pubnub = pubnub;
            this.pubnub.init({publishKey: 'YOUR PUB_KEY', subscribeKey: 'YOUR SUB_KEY'});
            this.pubnub.subscribe({channels: [this.channel], triggerEvents: ['message']});
        }],
        ngOnInit: function () {
            var self = this;
            setInterval(function () {
                var hw = 'Hello World, ' + Date.now();
                    self.pubnub.publish({channel: self.channel, message: hw});
            }, 1000);
        }
    });
})(window.app || (window.app = {}));
import { Component } from '@angular/core';
import { PubNubAngular } from 'pubnub-angular2';

@Component({
    selector: "appComponent",
    template: "<ul>" +
    "<li *ngFor='let item of PubNub.getMessage(channel)'>{{item.message}}</li>" +
    "</ul>"
})
export class AppComponent {
    pubnub: PubNubAngular;
    channel: string;
    constructor(pubnub: PubNubAngular) {
        this.channel = 'my_channel';
        this.pubnub = pubnub;
        this.pubnub.init({
            publishKey: 'YOUR PUB_KEY',
            subscribeKey: 'YOUR SUB_KEY'
        });
        this.pubnub.subscribe({
            channels: [this.channel],
            triggerEvents: ['message']
        });
    }
    ngOnInit() {
        setInterval(() => {
            let hw = 'Hello World, ' + Date.now();
            this.pubnub.publish({
                channel: this.channel, message: hw
            });
        }, 1000);
    }
}

Another key feature of this SDK is the ability to trigger events in addition to passed in callbacks, getting the stack of all messages received and inject it directly in the HTML of your Angular Component. By default events will not be triggered.

To enable all possible events for certain methods, add triggerEvents:true option when you are subscribing a channels or channel groups.

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

pubnub.subscribe({
    channels  : ['my_channel1', 'my_channel2', 'my_channel3'],
    channelGroups: ['my_channelGroup1', 'my_channelGroup2'],
    withPresence: true,
    triggerEvents: ['message', 'presence', 'status']
});

You are free to use events as you need them, can use one, two or three like this is shown above or you can also use the shortest way with triggerEvents:true. However if you are going to use presence event; the triggerEvents option must be accompanied with withPresence: true when it is being subscribed the channel.

There are two ways to use getMessage, getPresence, getStatus methods to catch messages, presences, and status in a callback. The first is to register a channel or channel group in individual way and the second is to register a set of channels using an array, in which this array can be included channels and channel group at the same time.

		pubnub.getMessage('my_channel1', function (msg) {
			console.log(msg);
		});

		pubnub.getMessage('my_channelGroup', function (msg) {
			console.log(msg);
		});

		pubnub.getMessage(['my_channel1', 'my_channel2', 'my_channelGroup'], function(msg) {
			console.log(msg.message);
			console.log(msg.channel);
		});		
pubnub.getPresence('my_channel1', function(pse) {
    console.log(pse);
});

pubnub.getPresence('my_channelGroup', function(pse) {
    console.log(pse);
});

pubnub.getPresence(['my_channel1', 'my_channel2', 'my_channelGroup'], function(pse) {
    console.log(pse);
    console.log(pse.subscribedChannel);
});

Via the status listener, you can receive different events such as when the network is online (PNNetworkUpCategory), when the SDK is connected to a set of channels (PNConnectedCategory), etc... See the list of events available in the API Reference

		pubnub.getStatus('my_channel1', function(st) {
			console.log(st);
		});

		pubnub.getStatus('my_channelGroup', function(st) {
			console.log(st);
		});

		pubnub.getStatus(['my_channel1', 'my_channel2', 'my_channelGroup'], function(st) {
			console.log(st);
		});		

The getMessage method is more than a mechanism for registering a channel, a set of channels or even a channel group to a callback that acts like a receptor to receive messages in real time when it is included the triggerEvents option at the moment of subscribing channels. The getMessage method will assign a stack for each register, this allows you to seamlessly bind a PubNub channel to your HTML or a local variable in your code.

		<ul *ngFor="let item of pubnub.getMessage('my_channel')">
			<li>{{ item.message }}</li>
		</ul>		
		var myStack1 = pubnub.getMessage('my_channel');

		var myStack2 = pubnub.getMessage('my_channelGroup');

		var myStack3 = pubnub.getMessage(['my_channel', 'my_channelGroup']);		
		var myStack1 = pubnub.getMessage('my_channel', function(msg) {
			console.log(msg);
		});		

If you want to catch real time messages in your code and bind simultaneously these to your HTML. You will have to follow these steps.

		this.messages = pubnub.getMessage('my_channel', function(msg) {
		    console.log(msg);
		});		
		<ul *ngFor="let item of messages">
			<li>{{ item.message }}</li>
		</ul>		
pubnub.clean('my_channel1');

pubnub.clean('my_channelGroup');

pubnub.clean(['my_channel1', 'my_channel2']);	
    

A very important point to describe here is the individuality of each stack. In the previous snippet of code we show three examples for cleaning a stack. If you can see the channel cleaned in the first line also appears in third line but when it executes the first line is not going to clean the data that it holds in the stack registered as a set till the third line is executed.

Sometime cleaning is good when you want to flush the data hold for the stack of messages but it is likely that for your app's lifecycle clean is not enough then you need release the stack and catch again in run time. Releasing a stack works like cleaning, in the same way you set up your channels you have to release them.

pubnub.release('my_channel1');

pubnub.release('my_channelGroup');

pubnub.release(['my_channel1', 'my_channel2']);
    

Autoload is extra parameter that you can pass at the moment of subscribing a channel, this allows to get the last messages stores in a fast and asynchronous way if your keys let to use this feature.

		pubnub.subscribe({
			channels: ['my_channel'],
			triggerEvents: true,
			withPresence: true,
			autoload: 100
		});

		var messages = pubnub.getMessage('my_channel');		
In addition to the Hello World sample code, we also provide some copy and paste snippets of common API functions:

Instantiate a new Pubnub instance. Only the subscribeKey is mandatory. Also include publishKey if you intend to publish from this instance, and the secretKey if you wish to perform PAM administrative operations from this Angular2 V4 instance.

 

It is not the best practice to include secretKey in client-side code for security reason.

 
Set restore as true to allow catch up on the front-end applications.
pubnub.init({
    subscribeKey: 'YOUR SUB_KEY',
    publishKey: 'YOUR PUB_KEY',
    ssl: true
});
A listener lets you to catch up real time messages, get presence and status information if you do not want to use the getMessage, getPresence, getStatus methods. Remember add a listener before subscribing a channel.
pubnub.addListener({
    status: function(st) {
        if (st.category === "PNUnknownCategory") {
            var newState = {
                new: 'error'
            };
            pubnub.setState({
                state: newState
            },
            function (status) {
                console.log(st.errorData.message);
            });
        }
    },
    message: function(message) {
        console.log(message);
    }
});

pubnub.subscribe({
    channels: ['my_channel']
});
Call time() to verify the client connectivity to the origin:
pubnub.time(function(status, response) {
    if (status.error) {
        console.log(status.error);
    } else {
        console.log(response.timetoken);
    }
});
pubnub.subscribe({
    channels: ['my_channel'],
    withPresence: true
});
The response of the call is handled by adding a Listener. Please see the Listeners section for more details. Listeners should be added before calling the method.
Publish a message to a channel:
pubnub.publish(
    {
        message: {
            such: 'object'
        },
        channel: 'ch1',
        sendByPost: false, // true to send via post
        storeInHistory: false, //override default storage options
        meta: {
            "cool": "meta"
        } // publish extra meta with the request
    },
    function (status, response) {
        // handle status, response
    }
);
Get occupancy of who's here now on the channel by UUID:
Requires that the Presence add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys
pubnub.hereNow(
    {
        channels: ["my_channel"],
        channelGroups : ["my_channelGroup"],
        includeUUIDs: true,
        includeState: true
    },
    function (status, response) {
        console.log(status);
        console.log(response);
    }
);
Subscribe to realtime Presence events, such as join, leave, and timeout, by UUID. Setting the presence attribute to a callback will subscribe to presents events on my_channel:
Requires that the Presence add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys
pubnub.addListener({
    presence: function(m) {
        console.log(m);
    },
    message: function(message) {
        console.log(message)
    }
});

pubnub.subscribe({
    channels: ["my_channel"],
    withPresence: true
});
The response of the call is handled by adding a Listener. Please see the Listeners section for more details. Listeners should be added before calling the method.
Retrieve published messages from archival storage:
Requires that the Storage and Playback add-on is enabled for your key. How do I enable add-on features for my keys? - see http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys
pubnub.history(
    {
        channel: 'my_channel',
        count: 100, // 100 is the default
        stringifiedTimeToken: true // false is the default
    },
function (status, response) 
    {
        console.log(response);
    }
);
pubnub.unsubscribe({
    channels : ['my_channel']
});
The response of the call is handled by adding a Listener. Please see the Listeners section for more details. Listeners should be added before calling the method.