Mini-Games operations

Mini-Games operations are responsible for communicating with Mini-Games API.

The namespace is of course called miniGames. All methods return promises. The general design of the namespace follows this pattern unless stated otherwise:

πŸ“˜

General call:

sdk.miniGames
  .someMethod()
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

The responses are comprised of different objects you can find here.

Classic Quiz related operations

Get classic quizzes

Method: getClassicQuizzes(filters?, showFullContextData?, disableCache?)

Method returns list of Classic Quizzes.

No authentication required.

The response from API is cached for 1 hour. With disableCache argument you can avoid cached response.

Filters object:

  • status: string. Options include: "ACTIVE" and "INACTIVE"
  • flags: array. A list of flags who are set to the classic quizzes. Maximum number of flags are 10.
  • limit: number . How many classic quizzes will be returned in list.
  • startAfter: string . The ID after which the classic quizzes should be listed. To be used in the context of infinite scroll/pagination.
  • entityIds: string[]. A list of entity ids who are set in Classic Quizz context. Maximum number of entityIds are 10.
  • entityType: string. The entity type can be 'competition', 'team' or 'player'.
  • classicQuizIds: string[]. A list of classic quiz ids to filter out the response. Maximum number of classicQuizIds are 50.
  • sort: string. The result can be sort by created at and updated at field in ascending and descending order. Accepted values are:
    • created_at_asc
    • created_at_desc
    • updated_at_asc
    • updated_at_desc
  • groupByStatus: boolean. When set to true, the result will be grouped by classic quiz status.

Important notes:

entityType is required when entityIds filter is provided and in SDK configuration the idSchema is different than native. This is because JS SDK needs to know what type the entity ids are to be able to remap them internally.

If no value is provided for filters, then no filters will be aplied.

showFullContextData is a boolean parameter. When is set to true, it will return models for all context tags entitites. Default value is false

πŸ“˜

Example call:

sdk.miniGames
  .getClassicQuizzes()
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

const filters = {
  limit: 1,
  startAfter: "5nhifBwMffT8QOkG6jKBM1",
  flags: ["Classic Quiz"],
  status: "INACTIVE",
};

sdk.miniGames
  .getClassicQuizzes(filters)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result

{
   meta: {
      pagination: {
         nextPageStartsAfter: null,
         itemsPerPage: 1
      }
   },
   data: [
      {
         id: "5nhifBwMffT8QOkG6jKBM1",
         title: "Premier League Classic Quiz",
         description: "Premier League Classic Quiz",
         type: null,
         images: null,
         participationCount: 0,
         questionsCount: 2,
         status: "INACTIVE",
         flags: [
            "Premier League",
            "Classic Quiz"
         ],
         customFields: {
            field: "asd"
         },
         labels: {
            label: "asd"
         },
         branding: BrandingModel,
         adContent: "Ad content",
         context: MiniGamesContext,
         time: 10,
         averageScore: 0,
         perfectScore: 0,
         points: 10,
         scored: true,
         maxAttempts: 3,
         createdAt: "2024-03-13T10:13:32Z",
         updatedAt: "2024-03-13T10:13:32Z"
      }
   ]
}

Get classic quiz by ID

Method: getClassicQuizById(classicQuizId, includeCorrectOptionIds?, disableCache?)

Method returns classic quiz by ID.

No authentication required.

When includeCorrectOptionIds is set to true, then the correct field for each option in each question will be returned. By default will be set to false.

The response from API is cached for 1 hour. With disableCache argument you can avoid cached response.

πŸ“˜

Example call with no includeCorrectOptionIds provided:

sdk.miniGames
  .getClassicQuizById("classicQuizId")
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result

{
  id: "6d1ScrL6PZlwqpPINsgco9",
  title: "My first Classic Quiz!",
  description: "My first Classic Quiz!",
  images: {
    main: "https://imagestorage.com/mainimage.jpg",
    cover: "https://imagestorage.com/mainimage.jpg",
    mobile: "https://imagestorage.com/mainimage.jpg"
  },
  participationCount: 0,
  questionsCount: 1,
  status: "INACTIVE",
  flags: ["Premier League", "Classic Quiz"],
  rules: "Some rules",
  adContent: "Ad content",
  context: MiniGamesContext,
  customFields: {
    custom: "field"
  },
  labels: {
    label: "label"
  },
  time: 10,
  averageScore: 14.3,
  perfectScore: 22,
  points: 10,
  scored: true,
  maxAttempts: 3,
  branding: BrandingModel,
  questions: [
    {
      questionId: 1,
      question: "Who has more goals in Premier League?",
      images: {
        main: "https://imagestorage.com/mainimage.jpg",
        mobile: "https://imagestorage.com/mainimage.jpg"
      },
      embedCode: null,
      options: [
        {
          optionId: 1,
          option: "Cristiano Ronaldo",
          images: {
            main: "https://imagestorage.com/mainimage.jpg",
            mobile: "https://imagestorage.com/mainimage.jpg"
          },
          correct: null // null because we don't have includeCorrectOptionIds set to true
        },
        {
          optionId: 2,
          option: "Harry Kane",
          images: {
            main: "https://imagestorage.com/mainimage.jpg",
            mobile: "https://imagestorage.com/mainimage.jpg"
          },
          correct: null  // null because we don't have includeCorrectOptionIds set to true
        }
      ]
    }
  ],
  createdAt: "2024-02-17T20:03:40Z",
  updatedAt: "2024-02-17T20:03:40Z"
}

πŸ“˜

Example call with includeCorrectOptionIds provided:

sdk.miniGames
  .getClassicQuizById("classicQuizId", true)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result

{
  id: "6d1ScrL6PZlwqpPINsgco9",
  title: "My first Classic Quiz!",
  description: "My first Classic Quiz!",
  images: {
    main: "https://imagestorage.com/mainimage.jpg",
    cover: "https://imagestorage.com/mainimage.jpg",
    mobile: "https://imagestorage.com/mainimage.jpg"
  },
  participationCount: 0,
  questionsCount: 1,
  status: "INACTIVE",
  flags: ["Premier League", "Classic Quiz"],
  rules: "Some rules",
  adContent: "Ad content",
  context: MiniGamesContext,
  customFields: {
    custom: "field"
  },
  labels: {
    label: "label"
  },
  time: 10,
  averageScore: 14.3,
  perfectScore: 22,
  branding: BrandingModel,
  questions: [
    {
      questionId: 1,
      question: "Who has more goals in Premier League?",
      images: {
        main: "https://imagestorage.com/mainimage.jpg",
        mobile: "https://imagestorage.com/mainimage.jpg"
      },
      embedCode: null,
      explanation: "Some explanation for question",
      options: [
        {
          optionId: 1,
          option: "Cristiano Ronaldo",
          images: {
            main: "https://imagestorage.com/mainimage.jpg",
            mobile: "https://imagestorage.com/mainimage.jpg"
          },
          correct: false // we have includeCorrectOptionIds set to true
        },
        {
          optionId: 2,
          option: "Harry Kane",
          images: {
            main: "https://imagestorage.com/mainimage.jpg",
            mobile: "https://imagestorage.com/mainimage.jpg"
          },
          correct: true // we have includeCorrectOptionIds set to true
        }
      ]
    }
  ],
  createdAt: "2024-02-17T20:03:40Z",
  updatedAt: "2024-02-17T20:03:40Z"
}

Participate in Classic Quiz

Method: participateInClassicQuiz(classicQuizId, questions, includeCorrectOptionIds?)

Method creates a user participation for specific classic quiz.

Authentication required.

questions param is an array of objects.

includeCorrectOptionIds param is an optional boolean. When set to true, from participating response the correct option ID will be returned.

πŸ“˜

Example call:

const questions = [ { questionId: 1, optionId: 1 } ];

sdk.miniGames
  .participateInClassicQuiz("classicQuizId", questions)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Throws error message
  });

Example result

{
  classicQuizId: "classicQuizId",
  userId: "Y44CxUzkpHdypYxcVVlwIQiLNtD2",
  questions: [
    {
      questionId: 1,
      optionId: 1,
      correct: false,
      correctOptionId: null
    }
  ],
  correctOptions: 0,
  points: 0,
  attempts: 1
}

πŸ“˜

Example call:

const questions = [ { questionId: 1, optionId: 2 } ];

sdk.miniGames
  .participateInClassicQuiz("classicQuizId", questions, true)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Throws error message
  });

Example result

{
  classicQuizId: "classicQuizId",
  userId: "Y44CxUzkpHdypYxcVVlwIQiLNtD2",
  questions: [
    {
      questionId: 1,
      optionId: 2,
      correct: true,
      correctOptionId: 2
    }
  ],
  correctOptions: 1
}

Get user own Classic Quiz participations

Method: getMyClassicQuizParticipations(filters?)

Method returns user's own Classic Quiz participations.

Filters object:

  • limit: number . How many classic quiz participations will be returned in list.
  • startAfter: string . The ID after which the classic quiz participations should be listed. To be used in the context of infinite scroll/pagination.
  • classicQuizIds: string[]. A list of classic quiz ids to filter out the response. Maximum number of classicQuizIds are 50.
    N.B. When not provided the result will contain all classic quiz participations that user has.

Authentication required.

πŸ“˜

Example call:

const filters = {
  limit: 1,
  startAfter: "classicQuizId",
  classicQuizIds: ["classicQuizId"]
}

sdk.miniGames
  .getMyClassicQuizParticipations(filters)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Throws error message
  });

Example result

[
  {
    classicQuizId: "classicQuizId",
    correct: 1,
    classicQuizQuestions: 1,
    personalBest: 1,
    points: 10,
    answers: [
      {
        questionId: 1,
        optionId: 1,
        correct: true,
        correctOptionId: 1
      }
    ]
  }
]

Get Classic Quiz leaderboards

Method: getLeaderboardForClassicQuizzes(filters?)

Method returns specified Classic Quiz leaderboards.

Filters object:

  • limit: number . How many classic quiz leaderboards will be returned in list.
  • page: number . The number of the page.
  • classicQuizIds: string[]. A list of classic quiz ids to filter out the response.
    N.B. When not provided the result will contain all classic quiz leaderboards.

No authentication required.

πŸ“˜

Example call:

const filters = {
  limit: 1,
  page:1,
  classicQuizIds: ["classicQuizId", "classicQuizId2"]
}

sdk.miniGames
  .getLeaderboardForClassicQuizzes(filters)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Throws error message
  });

Example result

{
   meta: {
      pagination: {
         currentPage: 1,
         itemsPerPage: 10,
         totalItems: 3,
         numberOfPages: 1
      },
      filters: {
         classicQuizIds: "classicQuizId,classicQuizId2"
      }
   },
   data: [
      {
         position: 1,
         profileId: "Y44CxUzkpHdypYxcVVlwIQiLNtD2",
         profileModel: ProfileModel,
         points: 24
      },
      {
         position: 2,
         profileId: "b2xObSXtgLbp6FgWTXbuTPNUs5a2",
         profileModel: ProfileModel,
         points: 20
      },
      {
         position: 3,
         profileId: "PGdBkHS4cXeiFWhDBTnbx885gZ32",
         profileModel: ProfileModel,
         points: 4
      }
   ]
}

Get Classic Quiz user rankings

Method: getClassicQuizzesUserRanking(userId, filters?)

Method returns specified all user rankings for Classic Quiz.

Filters object:

  • limit: number . How many classic quiz rankings will be returned in list.
  • page: number . The number of the page.

No authentication required.

πŸ“˜

Example call:

const filters = {
  limit: 1,
  page:1,
}

sdk.miniGames
  .getClassicQuizzesUserRanking("userId", filters)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Throws error message
  });

Example result

{
   meta: {
      pagination: {
         currentPage: 1,
         itemsPerPage: 10,
         totalItems: 2,
         numberOfPages: 1
      }
   },
   data: [
      {
         position: 2,
         classicQuizId: "5p60YWuFcXXvEdrW4jga5X",
         classicQuizModel: ClassicQuizBasicModel,
         points: 20
      },
      {
         position: 1,
         classicQuizId: "2aJvT2K0aYVADMZSMg8Uz7",
         classicQuizModel: ClassicQuizBasicModel,
         points: 4
      }
   ]
}

Either/Or related operations

Get Either/Ors

Method: getEitherOrs(filters?, showFullContextData?, disableCache?)

Method returns list of Either/Ors.

No authentication required.

The response from API is cached for 1 hour. With disableCache argument you can avoid cached response.

Filters object:

  • status: string. Options include: "ACTIVE" and "INACTIVE"
  • flags: array. A list of flags who are set to the Either/Ors. Maximum number of flags are 10.
  • limit: number . How many Either/Ors will be returned in list.
  • startAfter: string . The ID after which the Either/Ors should be listed. To be used in the context of infinite scroll/pagination.
  • entityIds: string[]. A list of entity ids who are set in Either/Or context. Maximum number of entityIds are 10.
  • entityType: string. The entity type can be 'competition', 'team' or 'player'.
  • eitherOrIds: string[]. A list of Either/Or ids to filter out the response. Maximum number of eitherOrIds are 50.
  • sort: string. The result can be sort by created at and updated at field in ascending and descending order. Accepted values are:
    • created_at_asc
    • created_at_desc
    • updated_at_asc
    • updated_at_desc
  • groupByStatus: boolean. When set to true, the result will be grouped by Either/Or status.

Important notes:

entityType is required when entityIds filter is provided and in SDK configuration the idSchema is different than native. This is because JS SDK needs to know what type the entity ids are to be able to remap them internally.

If no value is provided for filters, then no filters will be aplied.

showFullContextData is a boolean parameter. When is set to true, it will return models for all context tags entitites. Default value is false

πŸ“˜

Example call:

sdk.miniGames
  .getEitherOrs()
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

const filters = {
  limit: 1,
  startAfter: "2AVwjSQcgfK25QYTXzlHDQ",
  flags: ["flag1"],
  status: "ACTIVE",
};

sdk.miniGames
  .getEitherOrs(filters)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result

{
   meta: {
      pagination: {
         nextPageStartsAfter: null,
         itemsPerPage: 1
      }
   },
   data: [
      {
         id: "2AVwjSQcgfK25QYTXzlHDQ",
         title: "asdasd",
         description: "asdsadas",
         images: {
            main: "https://...",
            cover: "https://...",
            mobile: "https://..."
         },
         flags: [
            "flag1",
            "flag2"
         ],
         status: "ACTIVE",
         winningCondition: "MORE",
         lives: 3,
         time: 10,
         points: [
            {
               correctSteps: 0,
               score: 10
            },
            {
               correctSteps: 5,
               score: 20
            },
            {
               correctSteps: 10,
               score: 50
            },
            {
               correctSteps: 15,
               score: 100
            }
         ],
         customFields: {
            custom: "field"
         },
         labels: {
            new: "label"
         },
         adContent: "Ad content",
         context: MiniGamesContext,
         branding: BrandingModel,
         type: null,
         createdAt: "2024-03-28T09:21:38Z",
         updatedAt: "2024-03-28T09:21:38Z"
      }
   ]
}

Get Either/Or by ID

Method: getEitherOrById(eitherOrId, disableCache?)

Method returns Either/Or by ID.

No authentication required.

The response from API is cached for 1 hour. With disableCache argument you can avoid cached response.

πŸ“˜

Example call:

sdk.miniGames
  .getEitherOrById("2AVwjSQcgfK25QYTXzlHDQ")
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result:

{
   id: "2AVwjSQcgfK25QYTXzlHDQ",
   title: "asdasd",
   description: "asdsadas",
   images: {
      main: "https://...",
      cover: "https://...",
      mobile: "https://..."
   },
   flags: [
      "flag1",
      "flag2"
   ],
   status: "ACTIVE",
   winningCondition: "MORE",
   lives: 3,
   time: 10,
   points: [
      {
         correctSteps: 0,
         score: 10
      },
      {
         correctSteps: 5,
         score: 20
      },
      {
         correctSteps: 10,
         score: 50
      },
      {
         correctSteps: 15,
         score: 100
      }
   ],
   customFields: {
      custom: "field"
   },
   labels: {
      new: "label"
   },
   context: MiniGamesContext,
   branding: BrandingModel,
   type: null,
   createdAt: "2024-03-28T09:21:38Z",
   updatedAt: "2024-03-28T09:21:38Z",
   rules: "asdasda",
   adContent: "AD content"
}

Get user own statistics for specific Either/Or game

Method: getMyEitherOrStats(eitherOrId)

Method returns user's own statistics for Either/Or game.

User JWT authentication required.

πŸ“˜

Example call:

sdk.miniGames
  .getMyEitherOrStats("2AVwjSQcgfK25QYTXzlHDQ")
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result:

{
   eitherOrId: "2AVwjSQcgfK25QYTXzlHDQ",
   personalBest: 20
}

Get results for specific Either/Or game

Method: getEitherOrResults(eitherOrId, disableCache?)

Method returns standings and breakdown for Either/Or game.

No authentication required.

The response from API is cached for 1 hour. With disableCache argument you can avoid cached response.

πŸ“˜

Example call:

sdk.miniGames
  .getEitherOrResults("2AVwjSQcgfK25QYTXzlHDQ")
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result:

{
   standings: [
      {
         userId: "Y44CxUzkpHdypYxcVVlwIQiLNtD2",
         userModel: ProfileModel,
         personalBest: 20
      }
   ],
   breakdown: [
      {
         rangeStartInclusive: 0,
         rangeEndInclusive: 10,
         totalUsers: 0
      },
      {
         rangeStartInclusive: 11,
         rangeEndInclusive: 20,
         totalUsers: 1
      }
   ]
}

Participate in Either/Or

Method: participateInEitherOr(eitherOrId, participation, onEitherOrParticipationCallbacks?)

Method creates a user participation for specific Either/Or game.

User JWT authentication required.

The participation argument can be null. When it's null, then the Either/Or participations starts and users receives first pair of options.

The method can be used in two situations:

With no provided callback

Then the participation is a default one. The SDK expects only the game instance and the participation.

Examples:

πŸ“˜

Example call:

// Start the game
sdk.miniGames
  .participateInEitherOr("2AVwjSQcgfK25QYTXzlHDQ", null)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result:

{
   instanceId: "Y44CxUzkpHdypYxcVVlwIQiLNtD2_2AVwjSQcgfK25QYTXzlHDQ",
   eitherOrId: "2AVwjSQcgfK25QYTXzlHDQ",
   gameStartedAt: "2024-03-28T13:52:44Z",
   currentStep: 0,
   currentStreak: 0,
   remainingSteps: 45,
   currentLives: 3,
   currentPoints: 0,
   personalBest: 20,
   steps: [
      {
         pairId: "5_7",
         userSelection: null,
         correct: null,
         played: false,
         timestamp: null,
         optionOne: {
            id: "5",
            label: "asdasd qweqwe5 asda sasd adas asd asd asdasd asda",
            images: {
               main: "https://5asdiqw0d9ias09dias09dias09dias09dias09diasd.com",
               mobile: "https://6"
            },
            value: null
         },
         optionTwo: {
            id: "7",
            label: "asdasd qweqwe7 asda sasd adas asd asd asdasd asda",
            images: {
               main: "https://5asdiqw0d9ias09dias09dias09dias09dias09diasd.com",
               mobile: "https://6"
            },
            value: null
         }
      }
   ]
}

πŸ“˜

Example call:

// Continue with the participation. Provide answer for the first pair.
sdk.miniGames
  .participateInEitherOr("2AVwjSQcgfK25QYTXzlHDQ", { pair: "5_7", answer: "5"} )
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result:

{
   instanceId: "Y44CxUzkpHdypYxcVVlwIQiLNtD2_2AVwjSQcgfK25QYTXzlHDQ",
   eitherOrId: "2AVwjSQcgfK25QYTXzlHDQ",
   gameStartedAt: "2024-03-28T13:52:44Z",
   currentStep: 1,
   currentStreak: 0,
   remainingSteps: 44,
   currentLives: 2,
   currentPoints: 0,
   personalBest: 20,
   steps: [
      {
         pairId: "5_7",
         userSelection: "5",
         correct: false,
         played: true,
         timestamp: "2024-03-28T13:52:48.716838917",
         optionOne: {
            id: "5",
            label: "asdasd qweqwe5 asda sasd adas asd asd asdasd asda",
            images: {
               main: "https://5asdiqw0d9ias09dias09dias09dias09dias09diasd.com",
               mobile: "https://6"
            },
            value: 15
         },
         optionTwo: {
            id: "7",
            label: "asdasd qweqwe7 asda sasd adas asd asd asdasd asda",
            images: {
               main: "https://5asdiqw0d9ias09dias09dias09dias09dias09diasd.com",
               mobile: "https://6"
            },
            value: 17
         }
      },
      {
         pairId: "2_3",
         userSelection: null,
         correct: null,
         played: false,
         timestamp: null,
         optionOne: {
            id: "2",
            label: "asdasd qweqwe2 asda sasd adas asd asd asdasd asda",
            images: {
               main: "https://2.com",
               mobile: "https://2"
            },
            value: null
         },
         optionTwo: {
            id: "3",
            label: "asdasd qweqwe3 asda sasd adas asd asd asdasd asda",
            images: {
               main: "https://3.com",
               mobile: "https://3"
            },
            value: null
         }
      }
   ]
}

With provided implementation of callbacks

When onEitherOrParticipationCallbacks paramater is provided JS SDK handles the countdown timer for the game and returns a participation response when countdown is finished and the user hasn't answered the question

Example calls:

πŸ“˜

Example call with class that implements IEitherOrParticipationCallback:

class ParticipationCallback implements IEitherOrParticipationCallback {
  // some logic...
  
  onTimerTick (seconds: number) {
    // On each second JS SDK returns the remaining seconds for answering the question
    // Use the seconds for a progress bar or something else...
  };

  onElapsedResponse (response: EitherOrParticipationModel) {
    // After the time is expired, JS SDK creates an invalid participation and sends it to API
    // Handle the elapsed response...
  };
}

const callback = new ParticipationCallback();

// Start the game
sdk.miniGames
  .participateInEitherOr("2AVwjSQcgfK25QYTXzlHDQ", null, callback)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

πŸ“˜

Example call with function that uses the callbacks

const callback = () => {
  const onTimerTick = (seconds: number) => {
   // On each second JS SDK returns the remaining seconds for answering the question
   // Use the seconds for a progress bar or something else...
  };

  const onElapsedResponse = (response: EitherOrParticipationModel) => {
    // After the time is expired, JS SDK creates an invalid participation and sends it to API
    // Handle the elapsed response...
  };

  return {
    onTimerTick,
    onElapsedResponse,
  };
};

// Start the game
sdk.miniGames
  .participateInEitherOr("2AVwjSQcgfK25QYTXzlHDQ", null, callback())
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Results are the same as the default use of the method

Calculate user's result percentile in Either/Or

Method: calculateEitherOrResultPercentile(eitherOrId, points)

Method calculates the user's percentile of his Either/Or participation

No authentication required.

πŸ“˜

Example call:

sdk.miniGames
  .calculateEitherOrResultPercentile("2AVwjSQcgfK25QYTXzlHDQ", 80)
  .then((response) => {
    // Handle response
  })
  .catch((error) => {
    // Handle error
  });

Example result:

N.B. Method returns null when no results is available in the Either Or

46.3