@tge-tech/tgquest-core NPM

@tge-tech/tgquest-core

Installation
Configuration
Usage with modal instance
Usage with web-component button
Usage with react
Additional settings
Theme variables
Traffic Source backend integration

Overview

Part of the @tge-tech/tgquest platform for Telegram applications.\ Provides a modal window for displaying quests to users. Users can follow links within the modal, complete the offered quests, and automatically receive the rewards you have pre-configured.

Installation

npm:

$ npm i @tge-tech/tgquest-core

yarn:

$ yarn add @tge-tech/tgquest-core

Configuration

tgquest.js:

import { createTgquestModal } from '@tge-tech/tgquest-core';

// Get your api key from https://tgquest.tge.tech/traffic-source/apps/{your_app_id}
const apiKey = 'API_KEY'

// Create modal instance
export const tgquestModal = createTgquestModal({
  apiKey,
})

Usage

With modal instance

html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Example</title>
  </head>
  <body>
    <button id="button">Open Modal</button>
    <script type="module" src="script.js"></script>
  </body>
</html>

script.js:

const openModalButton = document.getElementById('button')

openModalButton.addEventListener('click', () => tgquestModal.open())

With web-component button

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Example</title>
  </head>
  <body>
    <tgq-button></tgq-button>
  </body>
</html>

With react

export const App = () => {
  const onClick = () => {
    tgquestModal.open()
  }

  return (
    <div>
      <button onClick={onClick}>
        Open Modal
      </button>
    </div>
  )
}

Additional settings

Locale

A locale in which the text and quests will be displayed inside the modal.\ If locale is not provided, it will be set automatically depending on the user's Telegram language.

export const tgquestModal = createTgquestModal({
  // only 'en | 'ru' locale is available for now
  locale: 'en',
})

// or
tgquestModal.setLocale('ru')

Payload

If you want to show the modal to the user in several places of your application, you can pass different payloads to .open() method options.\ With this approach, you will be able to determine exactly where the user clicked on the link from.

tgquestModal.open({ payload: 'main page'})
// or
tgquestModal.open({ payload: 'profile page'})

On Quest Complete

You may want to perform some action after the user has completed the quest.\ To do this, you can pass the onQuestComplete callback to the .open() method options.

tgquestModal.open({ onQuestComplete: () => console.log('complete') })

Also you can pass the global onQuestComplete callback to modal config.\ This callback will be executed on any quest is completed.

export const tgquestModal = createTgquestModal({
  onQuestComplete: () => console.log('complete'),
})

// or
tgquestModal.setOnQuestComplete(() => console.log('complete'))

Theme

You can provide a theme mode or/and theme variables to customize the modal. Otherwise theme mode will be set automatically depending on the browser theme.

export const tgquestModal = createTgquestModal({
  theme: {
    mode: 'dark',
    variables: {
      '--tgq-z-index': 9999,
      '--tgq-spacing': '12px',
      '--tgq-color-accent': '#DEBE49',
    }
  },
})

// or
tgquestModal.setThemeMode('light')
tgquestModal.setThemeVariables({
  '--tgq-avatar-size': '80px',
  '--tgq-border-radius': '0',
})

Theme variables

Name	Default value (light/dark)	Description
`--tgq-font-family`	`Rubik, sans-serif`	-
`--tgq-z-index`	`2000`	z-index for modal component
`--tgq-spacing`	`20px`	gap and padding
`--tgq-avatar-size`	`128px`	width and height
`--tgq-avatar-offset`	`-40px`	offset from bottom for quest avatar container
`--tgq-border-radius`	`12px`	modal/quest avatar/buttons
`--tgq-align`	`start`	text (text-align) and quest avatar (flex) align
`--tgq-color-backdrop`	`#00000080`	-
`--tgq-color-accent`	`#019ADA`	reward/button/icon etc.
`--tgq-color-background`	`#FAFAFA` / `#242424`	modal background color
`--tgq-color-background-avatar`	`#FFFFFF` / `#343434`	quest avatar container bacground color
`--tgq-color-text`	`#242424` / `#FAFAFA`	title and description
`--tgq-color-text-button`	`#FFFFFF`	-
`--tgq-shadow`	`0px 4px 12px 0px #0000001A`	quest avatar container shadow

Traffic Source backend integration

If you are a traffic source, you want to reward your user for completing quests. It can be possible via backend integration of our platform.\ All you need to do is implement the webhook (HTTP POST request) that accepts JSON data with click information from tgquest platform. We will make a request every time when your user completes a quest and you can reward them.

Webhook example

URL

POST https://your-domain/api/tgquest/accrue_reward

Request Headers

{
  // Get your api key from https://tgquest.tge.tech/traffic-source/apps/{your_app_id}
  "Authorization": "API_KEY"
}

Request Body

{
  "click": {
    "id": 1,
    "payload": "main page", // the value that you provided in tgquestModal.open method
    "task_id": 1, // that the user completed
    "user_telegram_id": 000000001
  }
}

Success Response

{
  "done": true
}

Errror Response

If the request data is not valid or authorization failed, your backend should return the appropriate error code and message.

{
  "error": "The Authorization header missing or invalid"
}

Code	Message
400 Bad Request	Invalid body
401 Unauthorized	The Authorization header missing or invalid

Advertiser backend integration

If you are an advertiser, you have the option not to show your quest to users who are already in your project.\ To make this possible you need to implement the webhook (HTTP POST request) that accepts JSON data, and we will make a request before showing your quest to the user.

Webhook example

URL

POST https://your-domain/api/tgquest/user_exists

Request Body

{
  "telegram_id": 000000001
}

Success Response

{
  "exists": false // user does not exist
}

Errror Response

If the request data is not valid, your backend should return the appropriate error code and message.

{
  "error": "Invalid body"
}

Code	Message
400 Bad Request	Invalid body

@lingui/core @lit/task @telegram-apps/sdk lit valtio

4 months ago

5 months ago

6 months ago

7 months ago

7 months ago

8 months ago

8 months ago

8 months ago

8 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

9 months ago

10 months ago

10 months ago