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

    staticgetByID | 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) 

    staticgetFromUser | Parameter | Type | Description | |---------------|----------|-----------------| | id | string | The User ID |

    Promise<MemeSet[]>Gets a list of MemeSets from a user's ID

    await MemeSet.getFromUser("abcdef")

    staticgetFeaturedNonePromise<MemeSet[]>Gets the currently featured MemeSets

    await MemeSet.getFeatured()

    dynamicgetMemes | 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)

    dynamicMeme.getCreatorNonePromise<User>Gets the meme's creator.

    await (await myMemeSet.getMemes(false))[0].getCreator();

  • Properties

    idstringThe memeset's IDmemesMeme[] undefinedGets the quizzes that the user has createdMeme.idstringThe meme's IDMeme.setIdstringThe ID of the memeset that this meme is included inMeme.creatorIdstringThe ID of the creator of this memeMeme.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 "") |

    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 "") |

    Meme.imagestringThe meme's imageMeme.typestringThe 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

    staticgetByID | Parameter | Type | Default | Description | |-----------|----------|----------|-------------| | id | string | Required | The Quiz ID |

    Promise<Quiz>Gets a Quiz via it's ID

    await Quiz.getByID("abcdef")

    staticsearchParameterTypesDefaultDescriptionquerystring""The search queryfilters | 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 filtersPromise<Quiz[]>Searches for quizzes based on the query and filters

    await Quiz.search("apple", {createdBy: ["abcdef"]})

    dynamicgetCreatorNonePromise<User>Gets the quiz's creator.

    await myQuiz.getCreator()

  • Properties

    idstringThe quiz's IDcreator | Property | Types | Description | |------------|----------|---------------------| | id | string | The user's ID | | avatar | string | The user's avatar | | username | string | The user's username |

    tagIdsstring[]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 |

    subjectsstring[]The subjects that this quiz is associated withsubtopicsstring[]The subtopics that this quiz is associated withtopicsstring[]The topics that this quiz is associated withimagestringThe quiz's imagegradesnumber[]The grades that this quiz is associated withstats | 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 |

• Tag

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

  • Methods

    staticgetByID | 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)

    staticgetFromUser | 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")

    dynamicgetItems | 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)

    dynamicgetCreatorNonePromise<User>Gets the tag's creator.

    await myTag.getCreator()

  • Properties

    idstringThe tag's IDcreatorIdstringThe tag's creator's IDvisibilitybooleanThe tag's visibilitynamestringThe tag's nametypestringThe tag's type ("quiz", "game", "meme". I am yet to find a tag that does not have the "quiz" type)totalItemsnumberThe number of items enclosed within this tagitemsQuiz[] | undefinedThe 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 true2. 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

    staticgetByID | Parameter | Type | Default | Description | |-----------|----------|----------|---------------| | id | string | Required | The user's ID |

    Promise<User>Gets a user from their ID

    await User.getByID("abcdef")

    dynamicgetQuizzesNonePromise<Quiz[]>Gets the quizzes that the user has created

    await myUser.getQuizzes()

    dynamicgetMemeSetsNonePromise<MemeSet[]>Gets the memesets that the user has created

    await myUser.getMemeSets()

    dynamicgetTagsNonePromise<Tag[]>Gets all the tags that the user has created

    await myUser.getTags()

  • Properties

    idstringThe user's IDnumOfQuizzesnumberThe number of quizzes that this user has creatednumOfTagsnumberThe number of tags (or "collections") that this user has creatednumOfMemeSetsnumberThe number of memesets that this user has createdfirstNamestringThe user's first namelastNamestringThe user's last nameusernamestringThe user's usernameoccupationstringThe user's occupationavatarstringThe user's avatarcoursesAn 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 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

    dynamicjoinGameParametersTypesDefaultDescriptionpinstring numberRequiredThe room PINnamestring"jsQuizizz Bot"The name to join the room withavatarIDnumber1The ID of the avatar you would like to join with. TODO: Add Avatar ID's to a new static property within Gameoptions | 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) |

    Promise<Nothing>Joins the Quizizz game

    await myGame.joinGame(123456, "Not_A_Robot", {
        correctPoints: 1000
    });

    dynamicleaveGameNoneNothingLeaves the Quizizz Game. This will cause the disconnect event to fire

    myGame.leaveGame()

    dynamicskipQuestionNoneNothingSkips the current question

    myGame.skipQuestion()

    dynamicactivatePowerup | 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"])

    dynamicanswer | 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

    powerupsPropertyPowerup TitleDescriptiondouble-jeopardyDouble 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 parameter2xx2

    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 parameter50-5050-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 dataeraserEraser

    Eliminates one wrong option

    Adds one incorrect option to the ai property, and the incorrectAnswers property from the question event dataimmunityImmunity

    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 wanttime-freezeTime 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 parameterpower-playPower 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 parametersupersonicSupersonic

    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 parameterstreak-saverStreak 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 parameterglitchGlitch

    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 parameterstreak-boosterStreak 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 parametersend-giftGift

    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 powerupsroomRoom (See types.d.ts:78 for Room types)The game roomia(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 namestringThe client's nameoptionsobjectThe game options. This object has the same content as the options parameter, but fully populatedsocketWebSocketThe websocket that the client uses to connect to the roomindexnumberThe current question's indexavatarIDnumberThe client's avatar id

  • Events

    disconnect | Property | Types | Description | |----------|----------|-----------------------| | code | number | The disconnect code | | reason | buffer | The disconnect reason |

    disconnect event is fired when the client gets disconnected from the websocketstartNoneThe start event is fired when the game has starteddoneAnsweringNoneThe doneAnswering event is fired when the client has answered all the questionsjoinNoneThe join event is fired when the client successfully joins the gamepowerup | 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 activatedgameEndedLeaderboard[] The gameEnded event is fired when the game has endedkick | Type | Description | |----------|-----------------| | string | The player's ID |

    The kick event is fired when a player has been kicked from the gameanswerPropertyTypesDescriptionstreak | Property | Types | Description | |-----------------|----------|-----------------------------------------| | currentStreak | number | The client's current streak | | maximumStreak | number | The client's highest streak in the game |

    isCorrectbooleanWhether the client was correct or notattemptnumberThe attempt on the question. (As of my testing, this value is always the same)scorenumberThe client's current scoreleaderboardLeaderboard[]The game's current leaderboardThe answer event is fired when the client answers a questionquestion | 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

    typestringThe content typemediaAn array of Media objects:PropertyTypesDescriptiontypestringThe media typevideostringThe media's videometa | 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 |

    textstring[] stringThe content texthasMathbooleanWhether the content has mathmath | Property | Types | Description | |------------|------------|----------------| | latex | string[] | The latex math | | template | string | The template |

  • 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
    })
})();