Fix: Update the Scalable Pixel Streaming Frontend Docs migration url and add utilisation and reference docs

README.md

@@ -11,9 +11,18 @@ The SPS frontend is a lightweight implementation of Epic Games' [Pixel Streaming
 
 ## Documentation
 
-In general, the official Epic Games Pixel Streaming [frontend docs](https://github.com/EpicGames/PixelStreamingInfrastructure/tree/master/Frontend) should cover most common usage cases (as our library is simply a thin wrapper on that). However, some SPS frontend specific docs are listed below:
+### Utilising the Scalable Pixel Streaming Frontend
+Below is a comprehensive guide for accessing the Scalable Pixel Streaming Frontend. This guide includes where to download the library, how to consume it and how to customise it for usage in different projects.
+- [Scalable Pixel Streaming Frontend utilisation guide](./docs/frontend_utilisation_guide.md)
 
-- [Migrating from SPS frontend <=0.1.4](./docs/api_transition_guide.md)
+### Migrating from Scalable Pixel Streaming Frontend
+In general, the official Epic Games Pixel Streaming [Frontend docs](https://github.com/EpicGames/PixelStreamingInfrastructure/tree/master/Frontend) should cover most common usage cases (as our library is simply a thin wrapper on that). However, some Scalable Pixel Streaming Frontend specific docs are listed below:
+
+- [Migrating from Scalable Pixel Streaming Frontend <=0.1.4](./docs/api_transition_guide.md)
+
+### Scalable Pixel Streaming Frontend Reference section
+The Scalable Pixel Streaming Frontend is a part of a complex system which abstracts a lot of its complexities behind the library. Below is a useful collection of references which explain how the Scalable Pixel Streaming Frontend fits within Scalable Pixel Streaming as a whole. 
+- [Scalable Pixel Streaming Frontend Reference guide](./docs/sps_frontend_refrence_guide.md)
 
 ## Issues
 

docs/api_transition_guide.md

@@ -0,0 +1,72 @@
+# Migrating from `libspsfrontend` <=0.1.4
+
+All SPS versions after `0.1.4` are now using the [Epic Games' Pixel Streaming frontend](https://github.com/EpicGames/PixelStreamingInfrastructure/tree/master/Frontend). This shift to the Epic frontend has caused us to change both our API and our NPM packages.
+
+---
+
+# API Usage
+
+Below are common usage of SPS Frontend API that have now changed (this list is not exhaustive, if there are more you would like documented please open an issue).
+
+## Listening for UE messages
+
+**Before:** 
+```js
+iWebRtcController.dataChannelController.onResponse = (messageBuffer) => { 
+	/* whatever */ 
+}
+```
+
+**Now:**
+```js
+pixelstreaming.addResponseEventListener(name, funct)
+
+// or
+
+pixelstreaming.removeResponseEventListener(name)
+```
+
+(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/132))
+
+---
+
+## Sending messages to UE
+
+**Before:** 
+```js
+iWebRtcController.sendUeUiDescriptor(JSON.stringify({ /* whatever */ } )) 
+```
+
+**Now:**
+```js
+pixelstreaming.emitUIInteraction(data: object | string)
+```
+
+(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/132))
+
+---
+
+## Listen for WebRTC stream start?
+
+**Before:** 
+```js
+override onVideoInitialised()
+```
+
+**Now:**
+```js
+pixelStreaming.addEventListener("videoInitialized", ()=> { /* Do something */ });
+```
+
+(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/110))
+
+------
+
+### NPM Packages
+The old [`libspsfrontend`](https://www.npmjs.com/package/@tensorworks/libspsfrontend) package is now deprecated in favour of [`spsfrontend`](https://www.npmjs.com/package/@tensorworks/spsfrontend).
+
+Add `spsfrontend` to your project like so:
+
+```
+npm i @tensorworks/spsfrontend
+```

docs/sps-frontend-guide.md → docs/frontend_utilisation_guide.md

@@ -124,113 +124,4 @@ config.setTextSetting(TextParameters.SignallingServerUrl, "wss://your.websocket.
 By default the Scalable Pixel Streaming Frontend contains all the requirements to connect to a Scalable Pixel Streaming signalling server making it an effective starting template for further customisation rather than starting from scratch. For further ways to utilise the the Pixel Streaming Frontend refer to the [Pixel Streaming Frontend documentation](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).   
 
 ### Scalable Pixel Streaming Frontend UI element customisation
-Further customisation of UI elements like Overlays or visual elements can be achieved by utilising the Pixel Streaming Frontend UI and extending its types. For further information on how to utilise the Epic Games Pixel Streaming Frontend UI refer to the [Pixel Streaming Frontend UI documentation](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).
-
----
-# Migrating from `libspsfrontend` <=0.1.4
-
-All SPS versions after `0.1.4` are now using the [Epic Games' Pixel Streaming frontend](https://github.com/EpicGames/PixelStreamingInfrastructure/tree/master/Frontend). This shift to the Epic frontend has caused us to change both our API and our NPM packages.
-
----
-
-# API Usage
-
-Below are common usage of SPS Frontend API that have now changed (this list is not exhaustive, if there are more you would like documented please open an issue).
-
-## Listening for UE messages
-
-**Before:** 
-```js
-iWebRtcController.dataChannelController.onResponse = (messageBuffer) => { 
-	/* whatever */ 
-}
-```
-
-**Now:**
-```js
-pixelstreaming.addResponseEventListener(name, funct)
-
-// or
-
-pixelstreaming.removeResponseEventListener(name)
-```
-
-(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/132))
-
----
-
-## Sending messages to UE
-
-**Before:** 
-```js
-iWebRtcController.sendUeUiDescriptor(JSON.stringify({ /* whatever */ } )) 
-```
-
-**Now:**
-```js
-pixelstreaming.emitUIInteraction(data: object | string)
-```
-
-(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/132))
-
----
-
-## Listen for WebRTC stream start?
-
-**Before:** 
-```js
-override onVideoInitialised()
-```
-
-**Now:**
-```js
-pixelStreaming.addEventListener("videoInitialized", ()=> { /* Do something */ });
-```
-
-(More details [here](https://github.com/EpicGames/PixelStreamingInfrastructure/pull/110))
-
-------
-
-### NPM Packages
-The old [`libspsfrontend`](https://www.npmjs.com/package/@tensorworks/libspsfrontend) package is now deprecated in favour of [`spsfrontend`](https://www.npmjs.com/package/@tensorworks/spsfrontend).
-
-Add `spsfrontend` to your project like so:
-
-```
-npm i @tensorworks/spsfrontend
-```
----
-# About the Scalable Pixel Streaming Frontend
-## SPS lifecycle
-### Authentication Phase
-1) The signalling server transmits a message to the frontend indicating that authentication is required.
-
-2) The player controller responds with an authentication request containing either an empty authentication token (if we have not yet received a token from an identity provider) or with an authentication token that had been obtained by means of a redirect during a previous run of the event lifecycle.
-
-3) The signalling server communicates with the authentication plugin to determine what to do next.
-
-- If the no-op authentication plugin is being used then the signalling server transmits a response indicating that authentication was successful.
-
-- If any other authentication plugin is being used and we do not have an authentication token then the signalling server transmits a response indicating that the user should be redirected to the login page for the identity provider.
-
-- If any other authentication plugin is being used and we do have an authentication token then the signalling server transmits a response indicating whether the token was accepted as valid by the authentication plugin.
-
-Note that the path taken in Step 3 is largely transparent to the logic in the Frontend.
-
-4) If a redirect is required then the Scalable Pixel Streaming Frontend will trigger it immediately after it has finished notifying the Epic Games Pixel Streaming Frontend of the authentication status. After a redirect occurs and the identity provider's login page subsequently redirects back to the Scalable Pixel Streaming Frontend, the page is reset and the event lifecycle restarts from the beginning, except that there is now an authentication token specified in the page's URL parameters and we will follow a different path in Step 3.
-
-5) Once the user has been successfully authenticated, the signalling server will initiate the creation of an instance of the Pixel Streaming application, which represents the beginning of the Instance Startup Phase.
-
-### Instance Startup Phase
-As the Pixel Streaming application instance is created and starts, the signalling server transmits status update messages to the Epic Games Pixel Streaming Frontend.
-
-The Epic Games Pixel Streaming Frontend notifies the Scalable Pixel Streaming Frontend of the application instance status so it can inform the user through the page's UI.
-
-Once the Pixel Streaming application instance has started, it will connect to the signalling server and initiate the WebRTC Connection Phase.
-
-### Determining the WebSocket endpoint URL
-Prior to deploying the Scalable Pixel Streaming Frontend, you will need to determine the endpoint URL that will be used to establish WebSocket connections to the signalling server(s) for your Pixel Streaming application:
-
-If you are deploying your Pixel Streaming application in a single geographic region on a single cloud platform, then this will be the signalling server endpoint URL reported by the Scalable Pixel Streaming REST API.
-
-If you are deploying your Pixel Streaming application in multiple geographic regions or across multiple cloud platforms then this will be the URL of a load balancer that you have configured to distribute requests to the signalling servers in the various regions or platforms.
+Further customisation of UI elements like Overlays or visual elements can be achieved by utilising the Pixel Streaming Frontend UI and extending its types. For further information on how to utilise the Epic Games Pixel Streaming Frontend UI refer to the [Pixel Streaming Frontend UI documentation](https://github.com/EpicGames/PixelStreamingInfrastructure#readme).

docs/sps_frontend_refrence_guide.md

@@ -0,0 +1,34 @@
+# About the Scalable Pixel Streaming Frontend
+## SPS lifecycle
+### Authentication Phase
+1) The signalling server transmits a message to the frontend indicating that authentication is required.
+
+2) The player controller responds with an authentication request containing either an empty authentication token (if we have not yet received a token from an identity provider) or with an authentication token that had been obtained by means of a redirect during a previous run of the event lifecycle.
+
+3) The signalling server communicates with the authentication plugin to determine what to do next.
+
+- If the no-op authentication plugin is being used then the signalling server transmits a response indicating that authentication was successful.
+
+- If any other authentication plugin is being used and we do not have an authentication token then the signalling server transmits a response indicating that the user should be redirected to the login page for the identity provider.
+
+- If any other authentication plugin is being used and we do have an authentication token then the signalling server transmits a response indicating whether the token was accepted as valid by the authentication plugin.
+
+Note that the path taken in Step 3 is largely transparent to the logic in the Frontend.
+
+4) If a redirect is required then the Scalable Pixel Streaming Frontend will trigger it immediately after it has finished notifying the Epic Games Pixel Streaming Frontend of the authentication status. After a redirect occurs and the identity provider's login page subsequently redirects back to the Scalable Pixel Streaming Frontend, the page is reset and the event lifecycle restarts from the beginning, except that there is now an authentication token specified in the page's URL parameters and we will follow a different path in Step 3.
+
+5) Once the user has been successfully authenticated, the signalling server will initiate the creation of an instance of the Pixel Streaming application, which represents the beginning of the Instance Startup Phase.
+
+### Instance Startup Phase
+As the Pixel Streaming application instance is created and starts, the signalling server transmits status update messages to the Epic Games Pixel Streaming Frontend.
+
+The Epic Games Pixel Streaming Frontend notifies the Scalable Pixel Streaming Frontend of the application instance status so it can inform the user through the page's UI.
+
+Once the Pixel Streaming application instance has started, it will connect to the signalling server and initiate the WebRTC Connection Phase.
+
+### Determining the WebSocket endpoint URL
+Prior to deploying the Scalable Pixel Streaming Frontend, you will need to determine the endpoint URL that will be used to establish WebSocket connections to the signalling server(s) for your Pixel Streaming application:
+
+If you are deploying your Pixel Streaming application in a single geographic region on a single cloud platform, then this will be the signalling server endpoint URL reported by the Scalable Pixel Streaming REST API.
+
+If you are deploying your Pixel Streaming application in multiple geographic regions or across multiple cloud platforms then this will be the URL of a load balancer that you have configured to distribute requests to the signalling servers in the various regions or platforms.