Merge branch 'master' into clarify-readme

README.md

@@ -1,16 +1,19 @@
-# Pusher Channels Angular Library
+# Pusher Channels AngularJS Library
 
 [![Build Status](https://travis-ci.org/pusher/pusher-angular.svg?branch=master)](https://travis-ci.org/pusher/pusher-angular)
 [![Coverage Status](https://img.shields.io/coveralls/pusher/pusher-angular.svg)](https://coveralls.io/r/pusher/pusher-angular?branch=master)
 
 This library is an open source client that allows you to connect to [Pusher Channels](http://pusher.com/channels). It keeps largely the same API as the [pusher-js library](http://github.com/pusher/pusher-js/), with a few differences.
 
+Currently only AngularJS (version 1.x) is supported.
+
 ## Usage overview
 
 The following topics are covered:
 
 * Initialisation
-* Subscribing to channels (public, private, and presence)
+* Subscribing to channels (public, private, encrypted and presence)
+* Accessing Channels
 * Binding to events
     * Globally
     * Per-channel
@@ -25,10 +28,10 @@ The first step is to make sure that you have all of the required libraries avail
 
 ````html
 <!-- AngularJS -->
-<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.4.0/angular.min.js"></script>
+<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.4.14/angular.min.js"></script>
 
 <!-- pusher-js -->
-<script src="//js.pusher.com/3.0/pusher.min.js"></script>
+<script src="//js.pusher.com/4.3/pusher.min.js"></script>
 
 <!-- pusher-angular -->
 <script src="//cdn.jsdelivr.net/npm/pusher-angular@latest/lib/pusher-angular.min.js"></script>
@@ -44,7 +47,7 @@ If you'd like you can use Bower to install pusher-angular using the following co
 bower install pusher-angular --save
 ````
 
-With that in place, to start using the Angular library you first need to create a Pusher client in exactly the same way that you create one using the [pusher-js library](http://github.com/pusher/pusher-js/), which is as follows:
+With that in place, to start using the `pusher-angular` you first need to create a Pusher client in exactly the same way that you create one using the [pusher-js library](http://github.com/pusher/pusher-js/), which is as follows:
 
 ````javascript
 var pusher = new Pusher(API_KEY);
@@ -60,7 +63,7 @@ var pusher = new Pusher(API_KEY, {
 
 This is all documented in full [here](http://github.com/pusher/pusher-js/).
 
-When you've created a Pusher client you then need to pass that client to a `$pusher` object inside your Angular controller, service, etc:
+When you've created a Pusher client you then need to pass that client to a `$pusher` object inside your AngularJS controller, service, etc:
 
 ````javascript
 angular.module('myApp').controller('MyController', ['$scope', '$pusher',
@@ -70,29 +73,29 @@ angular.module('myApp').controller('MyController', ['$scope', '$pusher',
 }]);
 ````
 
-You can also see here that you need to inject the `$pusher` service into any controllers, services, etc where you'd like to use Pusher in an Angular context.
+You can also see here that you need to inject the `$pusher` service into any controllers, services, etc where you'd like to use Pusher in an AngularJS context.
 
 To make the `$pusher` service available to be used throughout your app you need to ensure that the `pusher-angular` module is included in your app. You do this by having the following in your app:
 
 ````javascript
 angular.module('myApp', ['pusher-angular'])
 ````
 
-Note that you can choose to define just one Pusher client, should you prefer, and then use that as the client throughout your Angular app. You can do this by simply instantiating a client as follows:
+Note that you can choose to define just one Pusher client, should you prefer, and then use that as the client throughout your AngularJS app. You can do this by simply instantiating a client as follows:
 
 ````javascript
 window.client = new Pusher('API_KEY');
 ````
 
-and then instantiating instances of `$pusher` in your Angular app using the standard:
+and then instantiating instances of `$pusher` in your AngularJS app using the standard:
 
 ````javascript
 var pusher = $pusher(client);
 ````
 
-Make sure that you define client before then referencing it in your Angular app though.
+Make sure that you define client before then referencing it in your AngularJS app though.
 
-This is all of the setup required to have Pusher available in your Angular app. The content below will explain how you can utilise Pusher in an Angular app.
+This is all of the setup required to have Pusher available in your AngularJS app. The content below will explain how you can utilise Pusher in an AngularJS app.
 
 
 
@@ -142,6 +145,30 @@ for (var i = 0; i < channels.length; i++) {
 console.groupEnd();
 ````
 
+### Encrypted Channels (BETA)
+
+Like private channels, encrypted channels have their own namespace, 'private-encrypted-'. For more information about encrypted channels, please see the [docs](https://pusher.com/docs/client_api_guide/client_encrypted_channels).
+
+```js
+var my_private_encrypted_channel = pusher.subscribe('private-encrypted-my-channel');
+```
+
+## Accessing Channels
+
+It is possible to access channels by name, through the `channel` function:
+
+```js
+var my_private_encrypted_channel = pusher.channel('private-my-channel');
+```
+
+It is possible to access all subscribed channels through the `allChannels` function:
+
+```js
+pusher.allChannels().forEach(channel => console.log(channel.name));
+```
+
+Private, presence and encrypted channels will make a request to your `authEndpoint` (`/pusher/auth`) by default, where you will have to [authenticate the subscription](https://pusher.com/docs/authenticating_users). You will have to send back the correct auth response and a 200 status code.
+
 ## Binding to events
 
 Events can be bound to at 2 levels, the global, and per channel. They take a very similar form to the way events are handled in jQuery. Note that this is one area in which the API differs to pusher-js. In pusher-angular, a call to `bind` will return a decorated version of the callback / handler that you pass as a parameter. You will need to assign this to a variable if you wish to unbind the handler from the object in the future. This is explained in the docs for unbinding below.