Agora HQ Trivia Template

The Agora HQ Trivia template enables you to quickly get started with building a trivia game application. This tutorial will explain how to create an Agora account, download the HQ SDK, and use an Agora template branch to use as a framework for your Agora API application.

• General Overview
• Architecture Overview
• Hardware / Software Requirements
• How to Build the Environment
• Customize the UI
• Game Play Instructions
• Resources
• License

General Overview

Agora HQ Trivia is a live-streamed quiz show.

• Agora HQ Trivia Game Flow
• Agora SDKs and API Services

Agora HQ Trivia Game Flow

Players can participate in daily trivia games and win prize money. The game consists of a round of 10-12 questions. Each question has three answer choices.

• The host asks a the series of questions, each with increased difficulty.

• Players who correctly answer the question within the 10-second limit continue through the game. Players who answer incorrectly are eliminated from the game.

• At the end of the game, players that answer all the questions questions correctly, split the prize money.

Agora SDKs and API Services

The HQ Trivia template is a turnkey solution for live trivia game applications and uses the Agora SDK.

The special SDK is pre-packaged with the broadcast SDK and signaling SDK and IJK player framework.

Special SDK for IOS (Native media + signaling (chat) + SEI (V2_0_2)+IJK framework)

Special SDK for Android Signaling(chat) Special SDK for Android Native media + SEI (V2_0_2)+IJK framework

Note: The Agora Special SDK is required to run the HQ Trivia game demo and templates.

The figure above, show the template solution breakdown, along with the features each service would handle. The green blocks indicate services the Agora SDK currently provides.

SDK	SDK Description	API Description
Agora Signaling SDK (Included in the Special SDK)	The host broadcasts questions for the audience members to answer using messaging. This SDK: Manages communication between the audience members and the host Retrieves the number of current users in the channel Pushes questions and answers back and forth Acts as the synchronization mechanism (SEI)	Signaling service handles questions, answers, messaging, and comments
Agora Interactive Broadcast SDK (Included in the Special SDK)	The host/broadcaster pushes voice and video streams to the participants/audience/clients in real time	Media service handles audio/video streaming

Architecture Overview

The Agora HQ Trivia template provides a base architecture for a live quiz application network. The game members consist of at least one host and multiple audience members. The host quizzes the audience, and the audience member that answers all the questions correctly receives a prize.

The demo applications use a preconfigured test server and App ID, and can support up to 30,000 simultaneous audience members.

The Agora HQ Trivia demo consists of the following parts:

Application User	Description	System Requirements	Link
Host (with OBS certificate)	Controls the quiz, and the host’s video stream Note: Using OBS will capture and include video of the host using the virtual camera.	Windows 7+ Permission to access camera Note: A working camera is required for the game players to see the host (broadcaster) on their mobile devices. OBS Studio with OBS virtual plugin (required if the host wants to use Open Broadcaster Software to enhance the the game broadcast)	Download Windows Note: If you run the application and see the error “can’t start because mfc130u.dll is missing”, download and this library to fix the issue.
Audience member	Receives / answers questions + chat with other audience members	iOS / Android	Download Android Connect your mobile device with a USB cable, then install the Android client application on your mobile device. Download Xcode project for iOS Note: There is no pre-compiled .ipa file for iOS available. For iOS, build the application in Xcode and run it on your physical device. Ensure the application uses valid provisioning profile.
All users	Handles data flow between all users	NodeJS server with quiz pool	Download source for NodeJS

For instructions on how to run the demo see the Game Play Instructions.

• Template Application Types
• Template Branches
• Communication Breakdown
• Sample App Resources

Template Application Types

The template consists of two main application types:

Application Type	Platform
Host application	Windows only
Audience member application	iOS and Android

Note: All game members (host and audience) must join with the same Agora App ID and channel name, or they will not be entered into the same game.

Host Features

The host controls the game configuration and settings for all audience members that join the game.

• Pre-configuration settings
• Start hosting a game
• Join / leave a channel
• Send a question
• Publish question to audience members
• Restart the game

Audience Member Features

• Join / leave a channel
• Receive a question
• Answer a question
• View game results

Template Branches

There are three main game show templates available. Each template has its own separate branch in the Github repository. Learn more about the choosing the a template branch for your project.

Template Model	Communication Flow	Description
Basic Live Broadcast Model		Allows the host to broadcast a live quiz for audience members to answer questions using messaging. Includes option to apply to add a co-host.
Co-host Model		Allows audience members to see the host and co-host (for example, a celebrity). The co-host can also interact with the host and answer questions.
Team Model		Allows the audience members to answer questions as a team. (This template was used in the demo provided here.)

Communication Breakdown

The main communication for the live application network consists of the host(s), services, and audience members. The image below depicts the general communication flow the HQ Trivia template uses:

Location	Label	Description
Left grey box	Room of the Host	Represents the host(s) for the application
Middle grey box	SD-RTN	Represents the Agora SDK services
Right grey box	User Group	Represents the audience members

Service	Description
Live Broadcast Service	The host(s) push realtime audio and video streams to the audience members using the Agora Interactive Broadcast SDK
Signaling Service	Facilitates communication between the audience and the host using the The Agora Signaling SDK Retrieves the number of current users in the channel Manages messaging between the host and the audience members Pushes questions and answers synchronously, ensuring the video stream is synchronized with the questions
Customer service	Manages non-Agora SDK communication between the host and audience members
RTMP Streaming	Handles sharing to social media platforms

Note: Audience members who join and become co-hosts will begin using the communication protocols and services as a host, rather than an audience member.

Hardware / Software Requirements

For mobile applications, use a physical device when publishing. Some simulators lack the functionality or the performance needed to run the Agora SDK functionality.

Platform	Software	OS / Device
Server	NodeJS	NodeJS enabled server
Windows	Visual Studio 2013 or higher OBS Studio (only required if running the game with OBS Studio enabled)	Windows 7 or higher
Android	Android Studio 3.0 or above	Android device (e.g. Nexus 5X)
iOS	Xcode 8.0+ (Ensure a valid provisioning profile is applied to your project, or it will not run)	Physical iOS device (iPhone or iPad)

How to Build the Environment

• Download the HQ SDK and Choose a Template Branch
• Create an Account and Obtain an App ID
• Obtain an App Certificate ID (Needed for Windows and iOS environments)
• Build your Project

Download the HQ SDK and Choose a Template Branch

Download the HQ 2nd Stage SDK here. The HQ 2nd Stage SDK is available for Android, iOS, and Windows.

Unzip the downloaded file and choose the most applicable template branch for project:

Branch	Description
master	Empty branch. Do not use.
Solution-With-AgoraHQSigKit	(Deprecated) Based on HQ 1st stage SDK, with basic HQ functions
Solution-for-TeamUpMode	Based on HQ 2nd stage SDK. Includes "Team" mode and "Host-in" mode.
Solution-for-TeamUpMode-Http	Encompasses functionality of Solution-for-TeamUpMode. Adds use of http as a communication protocol between the server and clients.
Solution-for-TeamUpMode-Http-obs-studio	Encompasses functionality of Solution-for-TeamUpMode-Http. Adds OBS support.

Create an Account and Obtain an App ID

To build and run the sample application, get an App ID:

1. Create a developer account at agora.io.
2. In the Dashboard that opens, click Projects > Project List in the left navigation.
3. Copy the App ID from the Dashboard to a text file. You will use this when you launch the app.

Obtain an App Certificate ID

1. In the Agora dashboard, ensure your project is in Edit mode and press Enable to enable the app certificate.

   

2. Click on the Dynamic Key Server is ready, I'm going to enable app certificate button to enable the app certificate.

   

3. A notification box will appear indicating a confirmation message sent to your registered email address. When you receive the email, click on the Go Confirm button in the email.

   

   Note: The email confirmation is only valid for 30 minutes, so ensure you confirm within that time period.

4. Click on the enable checkbox, then the Enable button to complete the process.

   

   Note: The Enable button can only be clicked after the checkbox is selected.

5. Click on the eye icon to display the app certificate. Copy the App Certificate from the Dashboard to a text file. You will use this when you build the app for iOS.

   

Build your Project

To fully run the project, you will need to set up your environment with a server app (NodeJS), host app (Windows), and at least one audience member app (Android or iOS).

• Build for NodeJS (Server app)
• Build for Windows (Host app)
• Build for Android (Audience member app)
• Build for iOS (Audience member app)

Build for NodeJS

In the modules/config.js file, replace YOUR_APP_ID with your Agora App ID.

module.exports = {
    agora_appid: "YOUR_APP_ID",
    cc_id: "agora_hq_cc_server_en",
    sig_server: "SIG_SERVER"
};

Open the Terminal app and navigate to the project directory.

Install the project using the command npm install

Start the server using the command node server.js

Build for Windows

In the HQConfig.ini file, copy the Agora App ID, append the following information:

Property	Description	Value
AppId	Agora App ID	Your App ID from the Agora Dashboard
AppCertEnable	Defines if an app certificate will be used	true or false
AppCertificateId	Agora App Certificate	App Certificate from the Agora Dashboard (required if AppCertEnable is true)

[LoginInfo]
AppId=
AppCertEnable=
AppCertificateId=
ChannelName=HQ_Demo
LoginUid=
VideoSolutinIndex=
CameraDeviceName=
CameraDeviceID=

Ensure the Restart.bat file is in the same location as the execution directory.

Open the AgoraHQ.sln file in Visual Studio C++.

Use Build All Solution to build and run the project.

Build for Android

In the src/main/java/io/agora/agoraandroidhq/tools/Constants.java file, replace #YOUR_APPID with the App ID from the Agora dashboard.

public static final String AGORA_APP_ID = #YOUR_APPID;

Open the sample project in Android Studio.

Connect your Android device and run the project.

Note: Ensure a valid developer signing certificate is applied or your project will not run.

Build for iOS

Open the XCode project

In the KeyCenter.swift file:

- Replace `<#Your App Id#>` with your Agora App ID.
- Replace `<#Your App Certificate#>` with your Agora App Certificate

static let AppId: String = <#Your App Id#>
static let AppcertificateID:  String = <#Your App Certificate#>

Connect your iPhone／iPad device and run the project.

Note: Ensure you project has a valid provisioning profile or it will not run.

Customize the UI

There are two versions of the audience member application. One for Android, and the other for the iOS.

The audience member application consists of three main screens. The loading screen, the game screen, and the information screen. The screen layouts are customizable and use native UI components from Android Studio and Xcode.

Screen	Android View	iOS View	Functionality
Main screen			Displays when the next game will start Allows the user to log into a game Displays their prize winnings
Game screen			Where the user answers questions for the game
Information screen			Where the user can send the game to their friends or view contact information for the game owner

Game Play Instructions

• Start the Game as a Host
• Play the Game as an Audience Member

Start the Game as a Host

The host has the ability to start / end the game, and set game configuration parameters.

• Start the Application
• Enable OBS
• Set the Configuration
• Start the Game
• Play the Game

Start the Application

Run the AgoraHQ.exe file. Ensure the green bars are lit in the upper left corner. The green bars indicate a successful network connection.

Note: If the upper left corner is red instead of green, check your network connection before proceeding or the application will not run properly.

Enable OBS

Enabling OBS is optional. This gives users the ability to:

• Click the OBS image button to load a local picture
• Click the OBS camera button to launch the camera device
• Click the OBS media button to load a local media file

Note: OBS objects can be loaded one after another. OBS objects can:

• Move positions
• Change front/back relationships by right clicking the objects and selecting move up, move down, etc.
• Apply a red, blue, or green filter using the select filter dropdown menu

Enabling OBS, requires settings in the demo application and OBS Studio:

• Open the VirtualCam plugin
• Enable OBS in the Demo Application
• Add VirtualCam Filter

Open the VirtualCam plugin

If you don't have OBS Studio or the VirtualCam plugin, download the software and the plugin

In OBS Studio, open the VirtualCam plugin by selecting Tools -> VirtualCam.

Press the Start button and close dialog box.

Enable OBS in the Demo Application

1. Check OBS checkbox

   

2. Click on OBS Camera. This will open the properties window.

   

3. Choose a device from the Camera Device dropdown menu and press OK.

   Note: The available camera device options will vary, based on your system and hardware connections.

   

Add VirtualCam Filter

1. Add a filter to the source you want to output to the camera
.
2. Choose a sync camera target and press the Start button
.
3. If this camera is not yet active, the Start button will switch to a Stop button
 For more information about using OBS Studio, reference the official OBS Video Guide or reference the Agora Github Wiki.

Set the Configuration

1. Click on HQ Config to open the configuration window.

2. In the configuration window, set the configuration for your application:

   • Enter the Agora App ID into the APPID UI text field.

   • Select the appropriate region from the Region dropdown menu:

     • If the application will be used outside of mainland China select the Overseas Edition option.
     • If the application will be used in mainland China, select the Chinese Edition option.

     Note: After changing the region setting, the signal bar in the upper left corner of the app should turn green, indicating a successful connection.

   • Enter a channel name in the ChannelName UI text field. Ensure the channel name is the same as your audience members.

     Note: If running the demo application, do not change the channel name.

   • Select a camera from the CAMERA dropdown menu. If OBS is enabled, select OBS-Camera.

   

   Note: For security reasons, the production environment must enable a Dynamic key or Access Token (a new version of the Dynamic Key). Learn more about enabling it here.

3. Click OK to reboot the application. The application will restart, applying the updated configuration settings.

   

Start the Game

The following figure explains the game flow for the host, and how to hand out questions:

The last Send Question indicates the host will need to repeat the Send Question -> Start Question -> Stop Answer process again, until all questions are sent to the audience members. The game ends when all questions have been sent and answered.

Join the Channel

Click JoinChannel to start the game.

This starts the game, and the you will see your local camera view on the device.

Game Play Buttons

Command	Description
Send Question	Sends a question (and a set of multiple choice answers)
Start Question	Synchronizes the question with the video, allowing participants to see question on their mobile devices
Stop Answer	Stop audience members for answering the question. If this is pressed on the last question, the game ends. The host will receive the results of the game participants. Question：the sequence number of the current question Total: the total number of the participants Correct: the number of participants who answered correctly Wrong: the number of participants who answered incorrectly Answer: the number of correct answers A/B/C/D: the number of participants selecting each answer option rightPercent: the percentage of correct answers
Reset Question	Resets the game to the beginning. It restarts the answering process without changing the quiz set.

Play the Game

1. Press Send Question to send the questions to audience members
2. Press Start Question to display the question to audience members

Note: To ensure synchronization between the questions and the video, click Start Question after Send Question so all users in the channel will be able to see the questions at the simultaneously.

Note: The Start Question, and Stop Answer buttons are highlighted in blue to indicate the button can be pressed. Buttons are greyed out to indicate the button can not be pressed. Pressed buttons turn grey to prevent selection errors

Press Stop Answer to stop audience members from answering the question.

Press Reset Question at any time, to restart the game.

End of Game

At the end of the game, the results will display.

Play the Game as an Audience Member

Start the application on your iOS or Android device.

Enter the same Channel Name as the host. Once you have successfully logged in, you will see the broadcaster’s video.

Note: If the host has not started the game in the specified channel, a dialog box will appear, notifying the user that the channel is not found.

Play the Game

When the host clicks Start Question in their application, the audience member will see the question on their mobile device.

Click on an answer to the question. Repeat this process until the host stops sending questions.

During the game, users can chat with other audience members.

Game End

When the game ends, you will see a screen that shows the prize breakdown. The user can click START to play again.

Resources

• API documentation about the Interactive Broadcast SDK
• Complete API documentation is available at the Document Center.

License

This software is under the MIT License (MIT). View the license.