@tge-tech/tgquest-core
v1.0.2
Published
* [Installation](#installation) * [Configuration](#configuration) * [Usage with modal instance](#with-modal-instance) * [Usage with web-component button](#with-web-component-button) * [Usage with react](#with-react) * [Additional settings](#additional-set
Downloads
39
Readme
@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-coreyarn:
$ yarn add @tge-tech/tgquest-coreConfiguration
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_rewardRequest 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_existsRequest 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 |