README.md

Multiplayer quiz app built on Salesforce technology (host app)

1. About
2. Installation
   1. Requirements
   2. Host App Installation
   3. Player App Installation
   4. Host App Configuration
   5. Questions Setup
3. Performance and Scalability
4. Playing
5. Troubleshooting
6. Building / Developing
7. Contributing
8. Code of Conduct
9. License

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.

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 Heroku account to set it up.

Step 1: Host App Installation

There are two installation options for the host app:

Option 1: Managed Package (recommended)

If installing on a Developer Edition org, you first need to set up My Domain by following these instructions and keeping the default login policy.

1. Click this link to install the host app package and choose Install for All Users.

   You'll need to approve access to https://api.qrserver.com. We use this library to draw a QR Code.

2. Set up permissions:

   1. Navigate to Setup > Users > Permission Sets, click Quiz Host
   2. Click Manage Assignments
   3. Click Add Assignment
   4. Check your user and click Assign.

3. Navigate to Setup > Integrations > Change Data Capture, enable Change Data Capture for the Quiz Player object and Save.

Option 2: Scratch Org (for development purposes)

We assume that you have a working Salesforce DX environment (Salesforce CLI installed, Dev Hub configured and authorized). See this Trailhead project for guided steps.

1. Open a Terminal and clone the git repository:

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

2. 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

Step 2: Player App Installation

1. Generate a security token for your Salesforce user.

2. Generate a secure password using this service or any other. This will be the secret Quiz API Key that you'll set later in both applications.

3. Deploy the Quiz Player App to Heroku by clicking this button:

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

   Variable	Description
   QUIZ_API_KEY	The Quiz API key.
   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 user's password.
   SF_TOKEN	Your Salesforce user's security token.
   SF_USERNAME	Your Salesforce username.
   SF_NAMESPACE	The Salesforce package namespace (leave the sfq default value unless you are developing with a Scratch org).
   COLLECT_PLAYER_EMAILS	Whether the app should collect player emails (true/false).

Step 3: Host App Configuration

1. In your Salesforce org, go to Setup > Remote Site Settings and add a new site named Quiz_Player_App with the player app URL.

2. Generate a minified URL for the Heroku player app using this service or any other URL shortener (opt for a custom link for greater readability).

3. Go to Setup > Custom Metadata Types and click Manage Records next to Quiz Settings.

4. Click New and add a record with these values:

   Field	Description
   Player App URL	The Heroku player app URL.
   Player App URL Minified	The minified URL for the player app.
   Quiz API Key	The password that was generated earlier.
   Question Timer	The duration of the question timer (default: 12 seconds).

5. Using the App Switcher, navigate to the Quiz Lightning app. If the installation went well, the quiz page should appear with no errors:

At this point you can:

• test the game with the sample question.
• set up extra questions

Step 4: Questions Setup

Questions are stored as Quiz Question records.

The Quiz Session record controls the list of selected questions and specifies the questions' order. Use the component on this record page to rearrange questions (don't forget to save your changes).

You org should have one and only one Quiz Session record at any time.

Make sure to edit the Quiz Session record after adding new questions as they aren't automatically added to the quiz.

Option 1: Importing questions using the Data Import Wizard (Recommended)

You can create or import questions by adding records manually or by importing them in a CSV or XLS file with the Data Import Wizard.

Use this table template to save time:

Label	Answer A	Answer B	Answer C	Answer D	Correct Answer
1 + 1 = ?	1	2	3	4	B

Option 2: Importing questions using the Salesforce CLI

You can import questions with 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 folders:

   /data
   /CUSTOM_QUESTIONS
       /plan.json
       /sfqz__Quiz_Question__cs.json
       /sfqz__Quiz_Session__cs.json
       /sfqz__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
   

Performance and Scalability

Performance is critical to the game experience: it must be as close as possible to real-time.

In full transparency, we have no precise benchmark on how well the game scales and which kind of Dyno to use but here are some pointers:

• A free Heroku Dyno supports a 50 player game just fine.
• The app has worked flawlessly with 400 players on a Heroku Performance dyno but we never tested with more.

All the pressure lies on the Heroku infrastructure and in particular on the Node.js WebSocket server. We cannot guarantee how the network (sockets and load balancer) behave at large scale.

Note that Heroku datacenters are only available in North America and Europe. If you are running the quiz from another region (i.e.: India, Australia...), there's a chance that players will experience some lag.

Playing

🎥 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.
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 50+ 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.

Player app is not starting (Heroku error page is displayed)

• Check the Heroku app logs for the cause of the error. The app will refuse to start if your Salesforce credentials are incorrect (most likely error).
• Verify your Salesforce credentials in the configuration variables of your Heroku app.

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

• 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 configuration variables of your Heroku app.

Player app is slow/lags, questions do not show up on time

See the Performance and Scalability section.

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

• 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
  

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

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

Building / Developing

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.

Contributing

We love contributions, small or big, from others!

Please see our CONTRIBUTING guidelines. The first thing to do is to discuss the change you wish to make via issue, email, or any other method with the owners of this repository.

Also, review our code of conduct. Please adhere to it in all your interactions with this project.

Thanks goes to these wonderful ✨ people (emoji key) for contributing to the project:

Philippe Ozil 💻 🎨 🤔 📖 👀

mlezer-bd 📖

M Hamza Siddiqui 🛡️

This project follows the all-contributors specification. Contributions of any kind welcome!

📄 Code of Conduct

Please review and adhere to our CODE_OF_CONDUCT.md before contributing to this project in any way (e.g. creating an issue, writing code, etc).

📝 License

This project is licensed under the Creative Commons Zero v1.0 License. See the LICENSE file for details.