Take the battle

Battle taking process is quite similar to the one that is used for Challenges. Once the attempt is created, the user can start answering battle questions.

Get next question

The questions appear for both battle rivals in the same order and can be retrieved one by one, by execution of getNextBattleQuestion query.

Like in case of a challenge, battle questions will be returned not as iframe, but as a ChallengeQuestion object. The question form should and the answer submission should be implemented on the frontend.

Here is an example of the query execution:

query getBattleNextQuestion {
  getBattleNextQuestion(battleId: 1) {
    id
    title
    question
    answerAlternatives {
      key
      value
    }
    image {
      alt
      title
      url
    }
    timeLimit
  }
}

{
  "data": {
    "getBattleNextQuestion": {
      "id": "4",
      "title": "Select the correct answer",
      "question": "What is the capital of Switzerland?",
      "answerAlternatives": [
        {
          "key": "ucqGu5UP",
          "value": "Geneva"
        },
        {
          "key": "q8NPVbBJ",
          "value": "Bern"
        },
        {
          "key": "u1WrLxkW",
          "value": "Zurich"
        },
        {
          "key": "tVruIvyD",
          "value": "Basel"
        },
        {
          "key": "kor2EIrI",
          "value": "Lausanne"
        }
      ],
      "image": null,
      "timeLimit": 30
    }
  }
}

Submit the answer

To submit a battle answer, execute the saveBattleQuestionAnswer mutation. It has one argument - answerData:

Parameter	Type	Description
`battleId`	`ID`	Required. ID of the related battle.
`questionId`	`ID`	Required. ID of the question that is being answered.
`answerKey`	`ID`	Optional. The key of the selected answer alternative. If empty, the question will be considered as skipped.
`timeSpent`	`Int`	Required. The time that was spent to provide the answer. If the time spent is greater than the limit that is set in the question settings, the question will be considered as skipped.

Here is an example of the mutation execution:

mutation saveBattleQuestionAnswer {
  saveBattleQuestionAnswer(answerData: {battleId: 1, questionId: 4, answerKey: 'q8NPVbBJ', timeSpent: 8}) {
    errors
    response {
      givenAnswer {
        key
        value
      }
      correctAnswer {
        key
        value
      }
      isCorrect
      score
      attempt {
        cta {
          actionId
        }
      }
    }
  }
}

{
  "data": {
    "saveBattleQuestionAnswer": {
      "errors": [],
      "response": {
        "givenAnswer": {
          "key": "q8NPVbBJ",
          "value": "Bern"
        },
        "correctAnswer":  {
          "key": "q8NPVbBJ",
          "value": "Bern"
        },
        "isCorrect": true,
        "score": 10,
        "attempt": {
          "cta": [
            {
              "actionId": "NEXT_BATTLE_QUESTION"
            }
          ]
        }
      }
    }
  }
}

After the successful execution of the mutation, BattleQuestionAnswer object will be returned. When the answer for the last question is submitted, a battle attempt will be automatically closed, and the user will be able to check their results.

`BattleQuestionAnswer` object

A question answer is represented in Opigno Enterprise API as a BattleQuestionAnswer object:

Parameter	Type	Description
`attempt`	`BattleAttempt`	Required. The related battle attempt.
`correctAnswer`	`KeyValuePair`	Required. The correct answer.
`givenAnswer`	`KeyValuePair`	Optional. The given answer.
`id`	`ID`	Required. The answer ID.
`isCorrect`	`Boolean`	Required. A marker that indicates if the provided answer is correct or not.
`question`	`ChallengeQuestion`	Required. The related question. The same object as for challenges is used.
`score`	`Float`	Required. The number of points that the user got for the answer.
`timeSpent`	`Int`	Required. The time (in seconds) that is spent by the user to provide an answer for the related question.

Terminate battle attempt

Battles designed the same way as challenges, and all questions must be answered in a single attempt, without possibility to stop and resume it later. In this flow, a battle attempt should be terminated immediately if the user leaves the question page. To do this, execute the terminateBattleAttempt mutation.

Use extraTimeSpent parameter to add an extra time (in seconds) to the general time that the current API user spent on the given battle.

mutation terminateBattleAttempt {
  terminateBattleAttempt(battleId: 1, extraTimeSpent: 10) {
    errors
    response {
      id
      completedOn
      cta {
        actionId
        title
        arguments {
          key
          value
        }
      }
    }
  }
}

{
  "data": {
    "terminateBattleAttempt": {
      "errors": [],
      "response": {
        "id": "2",
        "completedOn": 1771193604,
        "cta": [
          {
            "actionId": "VIEW_BATTLE_RESULTS",
            "title": "View full results",
            "arguments": [
              {
                "key": "battleId",
                "value": "1"
              }
            ]
          }
        ]
      },
    }
  }
}

Getting started

Integration & Concepts

Use cases

Hierarchy Management

Zapier Integration

Mobile application

Take the battle

Get next question

Submit the answer

`BattleQuestionAnswer` object

Terminate battle attempt

​Get next question

​Submit the answer

​BattleQuestionAnswer object

​Terminate battle attempt

Get next question

Submit the answer

`BattleQuestionAnswer` object

Terminate battle attempt