Skip to content

Latest commit

 

History

History
559 lines (475 loc) · 17.5 KB

Documentation.md

File metadata and controls

559 lines (475 loc) · 17.5 KB
Raw

Kahoot.js Documentation

Table of Contents

  1. Classes
  2. Kahoot
  1. Quiz
  1. Question
  1. QuestionEndEvent
  1. QuestionSubmitEvent
  1. Nemesis
  1. FinishTextEvent
  1. QuizFinishEvent
  1. Q and A
  2. Using Proxies

Classes

Kahoot

The kahoot client that interacts with kahoot's quiz api.

Events

on('ready') and on('joined')

  • Emitted when the client joins the game.

on('quizStart', Quiz) and on('quiz', Quiz)

  • Emitted when the quiz starts for the client.
  • Passes a Quiz class.

on('question', Question)

  • Emitted when the client receives a new question.
  • This is NOT the same as the questionStart event, which is emitted after the question has started.
  • Passes a Question class.

on('questionStart', Question)

  • Emitted when a question starts.
    • Questions can be answered using Question.answer(data)
  • Passes a Question class.

on('questionSubmit', QuestionSubmitEvent)

  • Emitted when your answer has been submitted.
  • Passes a QuestionSubmitEvent class.

on('questionEnd', QuestionEndEvent)

  • Emitted when a question ends.
  • Passes a QuestionEndEvent class.

on('finish', QuizFinishEvent)

  • Emitted when the quiz ends.
  • Passes a QuizFinishEvent class.

on('finishText', FinishTextEvent)

  • Emitted when the quiz finish text is sent.
  • Passes a FinishTextEvent class.

on('quizEnd') and on('disconnect')

  • Emitted when the quiz closes, and the client is disconnected.

on('2Step')

  • Emitted when the 2 Step Auth is recieved
  • Emitted when the 2 Step Auth is refreshed

on('2StepFail')

  • Emitted when the 2 Step Auth is incorrect

on('2Step')

  • Emitted when the 2 Step Auth is correct

on('feedback')

  • Emitted when the host requests to see feedback.

on('invalidName')

  • Emitted when the join name is a duplicate.

on('handshakeFailed')

  • Emitted when the the websocket connection failed/was blocked.

Methods

join(sessionID, playerName, teamNames)

  • Joins the game.
  • Parameters:
    • sessionID (Number) - The Kahoot session ID to join.
    • playerName (String) - The name of the user.
    • teamNames (Array) [String] - The names of the team members to be used in team game modes (optional).
    • Returns: Promise

reconnect()

  • Reconnects the bot.
  • Should be used if connection is lost (network issue).
  • Returns: undefined

answerQuestion(id)

  • Answers the current question.
  • Parameters:
    • id (Number|Array|String)
      • for type "quiz," use a number (0-3) to specify the choice.
      • for type "open_ended" and "word_cloud," use a string to specify the answer.
      • for type "jumble," use an array of numbers (0-3) to specify the order of items.
    • Returns: Promise

answer2Step(steps)

  • Answers the 2 Step Auth.
  • Parameters:
    • steps (Array)
      • An array of the steps for the 2 step authentification. (numbers 0-3)
    • Returns: Promise

leave()

  • Leaves the game.
  • Returns: Promise

sendFeedback(fun, learning, recommend, overall)

  • Sends feedback to the host.
  • Parameters:
    • fun (Number)
      • A number to rate how much fun you had (1-5)
    • learning (Number)
      • A number to rate if you learned anything (1 or 0)
    • recommend (Number)
      • A number to rate if you would recommend (1 or 0)
    • overall (Number)
      • A Number to rate how you felt (-1 - 1)
        • 1 = good
        • -1 = bad
  • Returns: Promise

Properties

sendingAnswer (Boolean)

  • Whether or not the client is currently sending an answer.

token (String)

  • The client token of the user.

sessionID (Number)

  • The session ID of the quiz.

name (String)

  • The user's name.

quiz (Quiz)

  • The current quiz of the client.

nemesis (Nemesis)

  • The client's nemesis. (Will be null if the client does not have a nemesis.)

nemeses (Nemesis Array)

  • An array of all the client's past nemeses.

totalScore (Number)

  • The client's accumulated score.

cid

  • The client's client id.

team (Array) [String]

  • The team member names.

gamemode (String)

  • The game mode of the kahoot.
    • classic - normal kahoot game.
    • team - kahoot game with teams.

loggingMode (Boolean)

  • Whether to log the messages from and to the server. Defaults to false.

usesNamerator (Boolean)

  • Whether the kahoot is using the namerator.

hasTwoFactorAuth (Boolean)

  • Whether the kahoot is using two factor authentification.

Quiz

Properties

client (Kahoot)

  • The client the quiz is attached.

name (String)

  • The name of the quiz.
    • Note: this value may be null if you joined the quiz after it started

type (String)

  • The quiz type.

currentQuestion (Question)

  • The current question the quiz is on.

questions (Question Array)

  • An array of every single question in the quiz. New questions get added as they come in.

questionCount (Number)

  • The number of questions in the quiz.

answerCounts (Array) [Number]

  • An array that shows the # of choices per question in the quiz.

Question

Methods

answer(number)

  • Parameters:
    • number (Number)
      • The question number to answer. (0 is the first answer, 1 is the second answer, etc.)

Properties

client (Kahoot)

  • The client attached to the question.

quiz (Quiz)

  • The quiz that the question for.

index (Number)

  • The index of the question.

timeLeft (Number)

  • The time left before the question starts.

type (String)

  • The question type.
    • "quiz" is the basic multiple choice quesiton.
    • "survey" is a poll, there aren't any points.
    • "content" is a slideshow, you don't need to answer this one.
    • "jumble" is a puzzle question, send an array of numbers to order the answers.
    • "open_ended" is a free response question; send text.
    • "word_cloud" is a free response poll; send text.

usesStoryBlocks (Boolean)

  • Whether or not the question uses 'Story Blocks'.
  • I still don't know what this means.

ended (Boolean)

  • Whether or not the question has ended.

number (Number)

  • The number of the question.

gamemode (String)

  • The game mode of the session. It can be either "classic" or "team."

QuestionEndEvent

Properties

client (Kahoot)

  • The client attached to the event.

quiz (Quiz)

  • The quiz that the event is attached to.

question (Question)

  • The question that the event is attached to.

correctAnswers (String Array)

  • A list of the correct answers.

correctAnswer (String)

  • The correct answer. (if there are multiple correct answers, this will be the first correct answer.)

text (String)

  • The text sent by Kahoot after a question has finished.

correct (Boolean)

  • Whether or not the client got the question right.

nemesis (Nemesis)

  • The client's nemesis. (Will be null if the client does not have a nemesis.)

points (Number)

  • The points earned from this question.

streak (Number)

  • The current correct streak.

rank (Number)

  • The rank of the client

total (Number)

  • The total score of the client

QuestionSubmitEvent

Properties

client (Kahoot)

  • The client attached to the event.

quiz (Quiz)

  • The quiz attached to the event.

question (Question)

  • The question attached to the event.

Nemesis

Properties

name (String)

  • The name of the nemesis user.

score (Number)

  • The score of the nemesis user.

isGhost (Boolean)

  • Whether or not the nemesis user is a ghost player or not.

exists (Boolean)

  • Whether or not the nemesis exists (All other values will be undefined if this is false)

FinishTextEvent

Properties

metal (String)

  • The medal recieved after the quiz.

QuizFinishEvent

Properties

client (Kahoot)

  • The client attached to the event.

quiz (Quiz)

  • The quiz attached to the event.

players (Number)

  • The number of players on the quiz.

quizID (String)

  • The ID of the quiz.
  • This is ONLY sent at the end of the quiz.

rank (Number)

  • The client's ranking on the quiz.

correct (Number)

  • The number of questions that were scored correct.

incorrect (Number)

  • The number of questions that were scored incorrect.

All events have a .rawEvent property, which contains the raw information from Kahoot.

Q and A

Using Proxies

This package (V1.2.12+) now has support for use of proxies. This will request the session information using the proxy, but the websocket will still be directly connected. Proxies can either be a String or an Object like so:

const proxy1 = "http://cors-server.example.com/";
const proxy2 = {
  proxy: "http://other-server.example.com/path/",
  options: {
    headers: {
      "X-Requested-With": "foobar"
    },
    method: "POST"
  },
  nopath: true
};

Example Usage:

const kahootJS = require("kahoot.js-updated");
const bots = [];
for(let i = 0; i < 10; ++i){
  let client;
  if(Math.round(Math.random())){
    client = new kahootJS(proxy1);
  }else{
    client = new kahootJS(proxy2);
  }
  client.join(pin);
  bots.push(client);
}

The Proxy Option

Proxies must be in this format in order to work:
https://sub.domain.top/<path>/<query>

  • The information is requested by appending the proxy to the start of the url:
    "https://sub.domain.top/path/" + "https://kahoot.it/reserve/session/12345/?12418"
  • This can be prevented by using the nopath option.

The options is the HTTP Request Options, which should only be used if the proxy service requires special headers to work. You can also set the method used.

Proxies are only used to specify HTTP requests for the tokens and for challenge games. If the websocket connection is blocked, you need to use a proxy/vpn for your server.