Documentation

Getting Started Guide

Using the Sample Web App

The Sample Web Application (SWA) is a good starting point for application developers.  It demonstrates integration with the GraphQL endpoint for resources and the OAuth server for authentication.

Features of the sample web application

• User authentication - OAuth authentication, retrieving access tokens, using refresh tokens, storing tokens, expiry of tokens
• Subscription tiers - Search, collections and playback take into account the sources available for the listener's subscription tier
• Search - Searching for sources like stations, albums, tracks, etc.
• Collections - Retrieving and displaying collected stations, albums, etc.
• Playback - Starting playback of sources from search results, collection list, or continue playback from user history on login,
• Playback - Controlling playback by pausing, playing, skipping, replaying
• Playback - Sending playback events such as track progress
• Feedback - Giving feedback on tracks by giving it a thumbs up or a thumbs down
• Profile - Retrieving and displaying user profile information

Run the SWA

1. Download the source code from the link below.  Once it is downloaded you will use the 'archive password' to unarchive the project files.
2. Find the README.md file in the root of the project and follow the instructions on setting up the project, doing your first build, run the application and tests.

Technical design

The SWA is a React Application, created using React’s create-react-app. State management is maintained using Redux. Apollo is used as GraphQL client library.

Let’s have a look at the root structure:

.
├── README.md
├── codegen.yml
├── package-lock.json
├── package.json
├── public
├── schema.graphql
└── src
    ├── __mocks__
    ├── app.jsx
    ├── app.test.jsx
    ├── components
    ├── config.js
    ├── containers
    ├── graphql
    ├── index.jsx
    ├── logo.svg
    ├── oauth
    ├── routes
    ├── serviceWorker.js
    ├── setupTests.js
    ├── store
    │   ├── actions
    │   └── reducers
    └── styles

The most important files/folders here are:

package.json	This is the package manager file, it contains all the dependencies and run scripts for the project
codegen.yml	Used to generate the fragment types from the schema for Apollo
schema.graphql	The GraphQL API schema
public	Created by create-react-app and contains your favicon and main html page
src	The directory for the source code of the application
README.md	Read more about how to get the application up and running

src

Let’s explore the src directory since this is the place where all code lives.

config.js	The configuration file with your OAuth and GraphQL API endpoint. Also contains your callback URL and client ID/secret pair.
app.jsx, index.jsx	Entry files for application.
assets	All the icons and images used in the UI of the application.
components and containers	React components used in the application.
graphql	Contains the Apollo client setup file with all the Pandora GraphQL queries and mutations used in the application.
oauth	The OAuth calls used in the application for Authentication and Authorization.
routes	The routes set up for the application navigation.
store	Redux store actions and reducers for application state management.
styles	Global styles for the application, including variables and typography.
__mocks__, setupTests.js	Mocks used for unit tests and the configuration for testing.

 

Important notes

CORS

Since the SWA is a client application and running on localhost, you will get CORS issues with the production GraphQL API endpoint.  Therefore, to run this successfully on your local machine you will need to start your browser with web security disabled. Here’s a command for Chrome on OSX as an example:

alias chrome="/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome"
chrome --args --user-data-dir="/tmp/chrome_dev_test" --disable-web-security

Application secret

Your application secret should be stored in a safe place and it is advised to not commit the key to any repositories.  The secret should never be in client-side configurations of your application, but rather stored and managed server-side.