jsQuizizz

Overview

jsQuizizz is a NodeJS Wrapper for the Quizizz API.

Installing

This package can be installed using NodeJS's package manager, npm.

npm install jsquizizz

Importing

To use the new esm syntax, set your type to module in your package.json. Click me for more information

• You can import the entire package into a single variable (esm)

  import * as Quizizz from 'jsquizziz'

• You can import certain parts of the package into different variables (esm)

  import {MemeSet, Quiz, Tag, User, Game} from 'jsquizziz'

• You can also import this package into non-esm modules (commonjs)

  var Quizizz = await import("jsquizizz")

Documentation

• MemeSet

  Quizizz shows the players memes after every question answered. These memes are stored in MemeSets, and the MemeSet class allows us to get these MemeSets

  • Methods

    Type	Method	Parameters	Returns	Description	Example
    static	getByID	Parameter Type Default Description id string Required The MemeSet ID save boolean false Whether to save the memes to memory for faster recall	Promise<MemeSet>	Gets a MemeSet via it's ID	await MemeSet.getByID("abcdef", false)
    static	getFromUser	Parameter Type Description id string The User ID	Promise<MemeSet[]>	Gets a list of MemeSets from a user's ID	await MemeSet.getFromUser("abcdef")
    static	getFeatured	None	Promise<MemeSet[]>	Gets the currently featured MemeSets	await MemeSet.getFeatured()
    dynamic	getMemes	Parameter Type Default Description save boolean false Whether to save the data to memory for faster recall	Promise<Meme[]>	Gets the memes from the MemeSet	await myMemeSet.getMemes(true)
    dynamic	Meme.getCreator	None	Promise<User>	Gets the meme's creator.	await (await myMemeSet.getMemes(false))[0].getCreator();

  • Properties

    Property	Types	Description
    id	string	The memeset's ID
    memes	Meme[] undefined	Gets the quizzes that the user has created
    Meme.id	string	The meme's ID
    Meme.setId	string	The ID of the memeset that this meme is included in
    Meme.creatorId	string	The ID of the creator of this meme
    Meme.top	Property Types Description text string The text on the top of the meme (May be "") color string The color of the text (May be "")	The top text of the meme (if there is any)
    Meme.bottom	Property Types Description text string The text on the top of the meme (May be "") color string The color of the text (May be "")	The bottom text of the meme (if there is any)
    Meme.image	string	The meme's image
    Meme.type	string	The meme's type (mainly "correct" and "incorrect", but others do exist)

• Quiz

  Quizizz is a service based of many, many quizzes. The Quiz class helps to fetch these quizzes.

  • Methods

    Type	Method	Parameters	Returns	Description	Example
    static	getByID	Parameter Type Default Description id string Required The Quiz ID	Promise<Quiz>	Gets a Quiz via it's ID	await Quiz.getByID("abcdef")
    static	search	Parameter Types Default Description query string "" The search query filters Parameter Types Default Description grade_type.aggs string[] N/A The grade types subject.aggs string[] N/A The subjects lang.aggs string[] N/A The languages occupation string[] N/A The creator's occupations cloned boolean[] N/A Whether the quiz is a clone of another isProfane boolean[] N/A Whether the quiz is profane type string[] N/A The type of quiz createdBy string[] N/A Who created the quiz {} The search filters	Promise<Quiz[]>	Searches for quizzes based on the query and filters	await Quiz.search("apple", {createdBy: ["abcdef"]})
    dynamic	getCreator	None	Promise<User>	Gets the quiz's creator.	await myQuiz.getCreator()

  • Properties

    Property	Types	Description
    id	string	The quiz's ID
    creator	Property Types Description id string The user's ID avatar string The user's avatar username string The user's username	Gets the quizzes that the user has created
    tagIds	string[]	A list of tags that this quiz is associated with. (This property's value is [] unless the quiz has been generated from the Tag.getItems() function)
    questions	Property Types Description id string The question's ID type string The question's type ("MCQ", "MSQ", "DRAW", "MATCH", etc) query QuestionContent The question's question options QuestionContent[] The question's options answer string|number|number[]|undefined The question's answer explain QuestionContent The question's answer explanation (If there even is an explanation) hasCorrectAnswer boolean Whether the question has a correct answer	The quiz's questions
    subjects	string[]	The subjects that this quiz is associated with
    subtopics	string[]	The subtopics that this quiz is associated with
    topics	string[]	The topics that this quiz is associated with
    image	string	The quiz's image
    grades	number[]	The grades that this quiz is associated with
    stats	Property Types Description played number The number of times this quiz has been played totalPlayers number The total number of players that have played this quiz totalCorrect number The total number of correct answers that have been submitted in this quiz totalQuestions number The total number of questions that have been answered in this quiz	The statistics of this quiz

• Tag

  User's can tag their quizzes to group them into sections. The Tag class can process these sections and quizzes

  • Methods

    Type	Method	Parameters	Returns	Description	Example
    static	getByID	Parameter Type Default Description id string Required The Tag ID save boolean false Whether to save the data to memory for faster recall	Promise<Tag>	Gets a tag via it's ID	await Tag.getByID("abcdef", false)
    static	getFromUser	Parameter Type Default Description id string Required The user's ID	Promise<Tag[]>	Gets a list of tags from a user's ID	await Tag.getFromUser("abcdef")
    dynamic	getItems	Parameter Type Default Description save boolean false Whether to save the data to memory for faster recall	Promise<Quiz[]>	Gets all the items tagged with this tag	await myTag.getItems(true)
    dynamic	getCreator	None	Promise<User>	Gets the tag's creator.	await myTag.getCreator()

  • Properties

    Property	Types	Description
    id	string	The tag's ID
    creatorId	string	The tag's creator's ID
    visibility	boolean	The tag's visibility
    name	string	The tag's name
    type	string	The tag's type ("quiz", "game", "meme". I am yet to find a tag that does not have the "quiz" type)
    totalItems	number	The number of items enclosed within this tag
    items	Quiz[] | undefined	The items enclosed in this tag. This property will always be undefined except on two circumstances: 1. You call the getItems method with the save parameter set to true 2. You call the getByID static method with the save parameter set to true

• User

  The User class is a class that holds several aliases to the other class methods that get content based on a user id

  • Methods

    Type	Method	Parameters	Returns	Description	Example
    static	getByID	Parameter Type Default Description id string Required The user's ID	Promise<User>	Gets a user from their ID	await User.getByID("abcdef")
    dynamic	getQuizzes	None	Promise<Quiz[]>	Gets the quizzes that the user has created	await myUser.getQuizzes()
    dynamic	getMemeSets	None	Promise<MemeSet[]>	Gets the memesets that the user has created	await myUser.getMemeSets()
    dynamic	getTags	None	Promise<Tag[]>	Gets all the tags that the user has created	await myUser.getTags()

  • Properties

    Property	Types	Description
    id	string	The user's ID
    numOfQuizzes	number	The number of quizzes that this user has created
    numOfTags	number	The number of tags (or "collections") that this user has created
    numOfMemeSets	number	The number of memesets that this user has created
    firstName	string	The user's first name
    lastName	string	The user's last name
    username	string	The user's username
    occupation	string	The user's occupation
    avatar	string	The user's avatar
    courses	An array of Course objects: Property Types Description displayName string The display name of this course internalName string The internal name of this course _id string The course's ID uniqueName string The unique name of this course	The courses that the user is enrolled with
    `organization`	| Property | Types | Description | |----------|----------|------------------------------| | `id` | `string` | The organization ID | | `name` | `string` | The name of the organization | | `type` | `string` | The type of the organization |	The user's organization (This may be undefined)

• Game

  The Game class is probably the most complex class in this package. This class allows you to join a Quizizz game as a client.

  • Methods

    Type	Method	Parameters	Returns	Description	Example
    dynamic	joinGame	Parameters Types Default Description pin string number Required The room PIN name string "jsQuizizz Bot" The name to join the room with avatarID number 1 The ID of the avatar you would like to join with. TODO: Add Avatar ID's to a new static property within Game options Parameters Types Default Description correctPoints number 1000 How many points to give the player if they answer correctly. (0-7500) incorrectPoints number 0 How many points to give the player if they answer incorrectly. (0-5000) time number 1 When Quizizz asks the client how long it took to answer, what should the client respond? streakBoost number 6 When the streak-boost powerup is used, how far should the streak be boosted? (This parameter is only client-side, and is used for point evaluation, but in our instance, we custom set the points, so this parameter serves no real purpose) The optional parameters for the game	Promise<Nothing>	Joins the Quizizz game	await myGame.joinGame(123456, "Not_A_Robot", { correctPoints: 1000 });
    dynamic	leaveGame	None	Nothing	Leaves the Quizizz Game. This will cause the disconnect event to fire	myGame.leaveGame()
    dynamic	skipQuestion	None	Nothing	Skips the current question	myGame.skipQuestion()
    dynamic	activatePowerup	Parameters Types Default Description pu string Required The powerup to use. (See the myGame.powerups array for the powerups) targets string[] [] For the send-gift powerup, you must specify a list of player IDs as targets. See powerups for more information on this unique powerup	Promise<Nothing>	Activates the powerup provided	await myGame.activatePowerup(myGame.powerups["50-50"])
    dynamic	answer	Parameters Types Default Description answer string number[] number Required The answer to the current question	Promise<Nothing>	Answers the current question with the answer provided	await myGame.answer(1)

  • Properties

    Property	Types	Description
    powerups	Property Powerup Title Description double-jeopardy Double Jeopardy Players get double points if they choose the answer correctly but lose it all if they choose the wrong answer This powerup serves no real purpose, as we custom set our points in the options parameter 2x x2 Players get twice the points for answering a question right This powerup serves no real purpose, as we custom set our points in the options parameter 50-50 50-50 Eliminates half of the incorrect options Adds half of the incorrect options to the ia property, and the incorrectAnswers property from the question event data eraser Eraser Eliminates one wrong option Adds one incorrect option to the ai property, and the incorrectAnswers property from the question event data immunity Immunity 2 attempts are allowed for answering the same question Gives you another attempt to answer the current question if you get it wrong, you can use this as many times as you want time-freeze Time Freeze The timer is frozen to allow players to answer 1 question This powerup serves no real purpose, as we custom set our time in the options parameter power-play Power Play All players in the quiz get 50% more points in 20 seconds This powerup applies to all players except the client, as the client's points are custom set in the options parameter supersonic Supersonic Get 1.5x points for 20 seconds with ultra fast gameplay This powerup serves no real purpose, as we custom set our points in the options parameter streak-saver Streak Saver Ensures a player’s streak against an incorrect answer This powerup serves no real purpose, as the streak saver is only client side (for points), and we custom set our points in the options parameter glitch Glitch All players' screens glitch for 10 seconds (does not add to scores) Nothing more needs to said about this. add-points +1000pt No description This powerup serves no real purpose, as we custom set our points in the options parameter streak-booster Streak Booster Apply to boost your streak counter by +6 This powerup serves no real purpose, as the streak booster is only client side (for points), and we custom set our points in the options parameter send-gift Gift Players can send another player an extra 800 points This powerup requires you to specify the targets parameter for the activatePowerup method. If you send a player more than 9 gifts in a single question cycle, their game will crash when they try to answer.	The available powerups
    room	Room (See types.d.ts:78 for Room types)	The game room
    ia	(number|number[]|string)[]	The list of invalid answers for the current question, this array is populated when the following powerups are used: 50-50, eraser, immunity
    name	string	The client's name
    options	object	The game options. This object has the same content as the options parameter, but fully populated
    socket	WebSocket	The websocket that the client uses to connect to the room
    index	number	The current question's index
    avatarID	number	The client's avatar id

  • Events

    Event	Data	Description
    disconnect	Property Types Description code number The disconnect code reason buffer The disconnect reason	The disconnect event is fired when the client gets disconnected from the websocket
    start	None	The start event is fired when the game has started
    doneAnswering	None	The doneAnswering event is fired when the client has answered all the questions
    join	None	The join event is fired when the client successfully joins the game
    powerup	Property Types Description name string The powerup's name visibleOptions number[] undefined The new visible options for the current question. Is always undefined unless the powerup used is 50-50 or eraser streakChangeBy number The streak boost that the client received. Is always undefined unless the powerup used is streak-booster	The powerup event is fired when a powerup has been successfully activated
    gameEnded	Leaderboard[]	The gameEnded event is fired when the game has ended
    kick	Type Description string The player's ID	The kick event is fired when a player has been kicked from the game
    answer	Property Types Description streak Property Types Description currentStreak number The client's current streak maximumStreak number The client's highest streak in the game The client's streak isCorrect boolean Whether the client was correct or not attempt number The attempt on the question. (As of my testing, this value is always the same) score number The client's current score leaderboard Leaderboard[] The game's current leaderboard	The answer event is fired when the client answers a question
    question	Property Types Description question QuestionContent The question query answers QuestionContent[] The answers incorrectAnswers (string|number[]|number)[] The incorrect options. This array populates when immunity is used, and the question is attempted again type string The question type (MCQ, MSQ, DRAW, MATCH, REORDER, BLANK, and a few others)	The question event is fired when the client needs to answer a question. (It is HIGHLY RECOMMENDED that the myGame.answer method is called within the listener for this event)

• Types

  • QuestionContent

    Property	Types	Description
    type	string	The content type
    media	An array of Media objects: Property Types Description type string The media type video string The media's video meta Property Types Description width number The media's width height number The media's height layout string The layout of the media text string The media's text content bgColor string The media's background color videoId string The video ID associated with the media start number The start time of the media end number The end time of the media duration number How long should the media run for? kind string The kind of media embeddable boolean Whether the media is embeddable title string The media's title lat number The latitude of the media long number The longitude of the media heading string The heading of the media pitch number The pitch of the media The media's metadata	The content's media
    text	string[] string	The content text
    hasMath	boolean	Whether the content has math
    math	Property Types Description latex string[] The latex math template string The template	The question's latex math

  • Leaderboard

    Property	Types	Description
    name	string	The player's name
    rank	number	The player's rank
    score	number	The player's final score

Examples

• A basic Quizziz Game client

// The only class we need is Game
import { Game } from './src/index.js';

// Everything is async, so we make a holder function
(async function() {
    // Create a new game
    const myGame = new Game();

    // setup the events
    myGame.on("disconnect", data => {
        console.log(`Oh no! You disconnected with exit code ${data.code}.\n The reason for disconnect was ${data.reason.toString()}`);
    })

    myGame.on('start', () => console.log("The game is starting"));

    myGame.on("doneAnswering", () => console.log("You answered all the questions!"));

    myGame.on("join", () => console.log("You're in!"));

    myGame.on("powerup", data => {
        console.log(`You used the ${data.name} powerup!`);
        if (["50-50","eraser"].includes(data.name)) {
            console.log(`Now, the possible answers are: ${data.visibleOptions.join(', ')}`)
        } else if (data.name === "streak-booster") {
            console.log(`Your streak has been boosted by ${data.streakChangeBy}!`)
        }
    });

    myGame.on("gameEnded", data => {
        data.forEach(leaderboard => {
            console.log(`${leaderboard.name} finished with a rank of #${leaderboard.rank} and a score of ${leaderboard.score}`)
        })
    });

    myGame.on("kick", data => console.log(`${data} was kicked from the game`));

    myGame.on("answer", data => {
        console.log(`You answered ${data.isCorrect ? "" : "in"}correctly on attempt #${data.attempt}. ${data.score} has been added to your score. Your streak is ${data.streak.currentStreak}.`)
    });

    myGame.on("question", data => {
        switch (data.type) {
            case "MATCH":
            case "MSQ":
            case "REORDER":
                myGame.answer(/* my answer */ Array(data.answers.length).fill(0).map((_0, index) => index))
                break;
            case "MCQ":
                myGame.answer(/* my answer */ 0)
                break;
            case "DRAW":
            case "BLANK":
                myGame.answer("I <3 RedYetiDev")
                break;
            default:
                console.log(data.type + ": Skipped");
                myGame.skip();
        }
    })

    // join the game
    myGame.joinGame("560018", "RedYetiDev", 1, {
        correctPoints: 2000,
        incorrectPoints: 500
    })
})();