ramkambalapally / quiz-host-app

Multiplayer quiz app built on Salesforce technology (host app)

Multiplayer quiz app built on Salesforce technology (host app)

1. About
2. Installation
   • Requirements
   • Steps
   • Setting up questions
3. Usage
4. Troubleshooting
5. Building and contributing

About

This application is a multiplayer game entirely built on Salesforce technology. A game host presents questions from a Salesforce Org on a shared screen or a video projector. Players compete by answering those questions in real-time using a Lightning Web Component Open Source mobile application hosted on Heroku. The fastest player to give the correct answer scores the most points. As the game progresses, leaderboards are displayed so that players can keep track of scores and ranks.

The quiz app was launched during Developer Game Night at Dreamforce 2019.

Installation

Requirements

The quiz requires two applications: a host app and a player app.

The host app is a Lightning Web Component (LWC) app running on a Salesforce Org. You'll need to set up Salesforce DX to deploy it.

The player app is a mobile app built with Lightning Web Component Open Source (LWC OSS). It runs on Node.js deployed on Heroku. You'll need a free Heroku account to set it up.

Steps

🎥 Watch the installation video

1. Set up your Salesforce DX environment:
   • Install Salesforce CLI
   • Enable Dev Hub on a Salesforce org. You can do that on a free Developer Edition.
   • Authenticate with your Dev Hub org and provide it with an alias (myhuborg in the command below):

     sfdx force:auth:web:login -d -a myhuborg

2. Open a Terminal and clone the git repository:

   git clone https://github.com/pozil/quiz-host-app.git
   cd quiz-host-app

   Tip: you can also download the files from the website if you don't want to install git.

3. Run the installation script. The script deploys the quiz host app on a scratch org with a quiz alias and pre-loads sample questions.

   MacOS or Linux

   ./install-dev.sh quiz sample

   Windows

   install-dev.bat quiz sample

   Once the script completes, it will open your new scratch org in a browser tab. If you close the tab or get disconnected, run this command to reopen the org sfdx force:org:open -u quiz

4. Generate a security token for your user
5. Generate a password using this service. This will be the secret Quiz API Key that you'll set later in both applications.
6. Deploy the Quiz Player App to Heroku by clicking this button:
   

   

7. Set the Config Vars for the Heroku Player app as following:

   Variable	Description
   QUIZ_API_KEY	The Quiz API key that was generated in step 5.
   SF_LOGIN_URL	The login URL of your Salesforce org: https://test.salesforce.com/ for scratch orgs and sandboxes https://login.salesforce.com/ for Developer Edition and production
   SF_PASSWORD	Your Salesforce password.
   SF_TOKEN	Your Salesforce user's security token that was generated in step 4.
   SF_USERNAME	Your Salesforce username.

8. Generate a minified URL for the Heroku player app using this service (I suggest a custom link for greater readability).
9. In your Salesforce org, go to Setup > Remote Site Settings and add the complete player app URL (not the minified URL).
10. Go to Setup > Custom Metadata Types and add a Quiz Settings record. Set it up with these values:

    Field	Description
    Player App URL	The Heroku player app URL that was generated in step 6.
    Player App URL Minified	The minified URL for the player app that was generated in step 8.
    Quiz API Key	The password that was generated in step 5.

Setting up questions

The default installation provides a limited set of sample questions but you can customize questions as you see fit as these are based on records.

Importing other questions

The easiest way to add new questions is to import them using the Salesforce CLI.

1. Get a zip with custom questions and extract in the data folder. Assuming that your custom question folder is named CUSTOM_QUESTIONS, you should have the following files and:

/data
  /CUSTOM_QUESTIONS
    /plan.json
    /Quiz_Question__cs.json
    /Quiz_Session__cs.json
    /Quiz_Session_Question__cs.json

2. Run this script to remove existing questions:

sfdx force:apex:execute -f bin/wipe-data.apex

3. Run this script from the project root to import your custom questions:

sfdx force:data:tree:import -p data/CUSTOM_QUESTIONS/plan.json

Adding/editing questions

You can add or edit Quiz_Question__c records to customize the game.

Follow this process to add a new question:

1. Create a Quiz_Question__c record with a question label, the four possible answers and a correct answer.
2. Create a Quiz_Session_Question__c to tie your Quiz_Question__c to the Quiz_Session__c. You'll need to specify an unique index number for the question. This index is used to order questions during the game.

Note: if you change the first quiz question, make sure to hit the reset button on the quiz host app.

Usage

🎥 Watch the playthrough video

Once you have installed the app, test it in private to confirm that it works.

Here is how the game works:

1. Open the Salesforce org. You log in with your browser or simply run this command: sfdx force:org:open -u quiz
2. Open the Quiz app from App Launcher.
3. Make sure that the screen is showing the Registration screen. If not, click the Reset button.
4. Open the mini URL or scan the QR code with your phone. That should open the player app.
5. Register on the player app. Your player name should automatically appear on the host app.
6. Click on the top right Start button on the host app. Once the game is started, players are no longer able to register.
7. Your player app should show a "Waiting for question" message for a few seconds then show the 4 answer buttons. If the player app does not refresh, you likely have a setup issue. See troubleshooting.

Scoring system

Players start with a zero score. The fastest player to answer a question correctly earns 1000 points. Players who also answered correctly but slower will earn a decreasing number of points depending on how late they answered. Wrong answers grant no points. The player that scores the most points at the end of the game wins.

Player app wake-up

Shortly before running the official game, make sure to access the player app a first time to load it.
The default Heroku setup uses a free Heroku dyno. This implies that apps that are inactive for more than 30 minutes are put to sleep. Any connection to the app will wake it up but it takes a bit less than a minute. You may experience some "Request time out" errors during that wake-up time.

If you are running the game with 40+ players, consider upgrading to a Hobby dyno.

Resetting the game

You can reset the game at any time by clicking on the Reset button on top right of the Quiz app. This resets the quiz session to the registration phase, clears players and previous answers.

Troubleshooting

Review these common problems. If you can't find a solution to your problem, open a new issue.

Problem: Player app is not updating when switching game phase (from registration to question for example)

Solution:

• Check that you have registered the correct Remote Site in your org.
• Check that your Quiz API Key is correctly set up in both the Custom Metadata Types and in the Heroku environment variable.

Problem: Something is wrong with the quiz data or you'd like to reset it

Solution:

• Reset the game using the Reset button on the quiz app. This resets the quiz session to the registration phase, clears players and previous answers.
• Run the following script wipe ALL quiz data. You'll have to reimport questions.

  sfdx force:apex:execute -f bin/wipe-data.apex
  

Problem: You're seeing a "Failed to validate Quiz app settings: Read timed out" error on the host app.

Solution: Refresh the page to fix the problem. Refer to the Player app wake-up section of this document for more information.

Building and contributing

If you want to build the project from sources and contribute, run npm install to install the project build tools.

Here is the Quiz Player App repository.