- About
- Installation
- Performance and Scalability
- Playing
- Troubleshooting
- Building / Developing
- Contributing
- Code of Conduct
- License
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.
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.
There are two installation options for the host app:
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.
-
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. -
Set up permissions:
- Navigate to Setup > Users > Permission Sets, click Quiz Host
- Click Manage Assignments
- Click Add Assignment
- Check your user and click Assign.
-
Navigate to Setup > Integrations > Change Data Capture, enable Change Data Capture for the Quiz Player object and Save.
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.
-
Open a Terminal and clone the git repository:
git clone https://github.com/forcedotcom/quiz-host-app.git cd quiz-host-app
-
Run the installation script. The script deploys the quiz host app on a scratch org with a
quiz
alias and pre-loadssample
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
-
Generate a security token for your Salesforce user.
-
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.
-
Deploy the Quiz Player App to Heroku by clicking this button:
-
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 sandboxeshttps://login.salesforce.com/
for Developer Edition and productionSF_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).
-
In your Salesforce org, go to Setup > Remote Site Settings and add a new site named
Quiz_Player_App
with the player app URL. -
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).
-
Go to Setup > Custom Metadata Types and click Manage Records next to Quiz Settings.
-
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). -
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
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.
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 |
You can import questions with the Salesforce CLI.
-
Get a zip with custom questions and extract in the
data
folder. Assuming that your custom question folder is namedCUSTOM_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
-
Run this script to remove existing questions:
sfdx force:apex:execute -f bin/wipe-data.apex
-
Run this script from the project root to import your custom questions:
sfdx force:data:tree:import -p data/CUSTOM_QUESTIONS/plan.json
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.
π₯ 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:
- Open the Salesforce org.
- Open the Quiz app from App Launcher.
- Make sure that the screen is showing the Registration screen. If not, click the Reset button.
- Open the mini URL or scan the QR code with your phone. That should open the player app.
- Register on the player app. Your player name should automatically appear on the host app.
- Click on the top right Start button on the host app. Once the game is started, players are no longer able to register.
- 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.
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.
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.
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!
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).
This project is licensed under the Creative Commons Zero v1.0 License. See the LICENSE file for details.