1.0.2 • Published 4 months ago

@tge-tech/tgquest-core v1.0.2

Weekly downloads
-
License
MIT
Repository
-
Last release
4 months ago

@tge-tech/tgquest-core

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

NameDefault value (light/dark)Description
--tgq-font-familyRubik, sans-serif-
--tgq-z-index2000z-index for modal component
--tgq-spacing20pxgap and padding
--tgq-avatar-size128pxwidth and height
--tgq-avatar-offset-40pxoffset from bottom for quest avatar container
--tgq-border-radius12pxmodal/quest avatar/buttons
--tgq-alignstarttext (text-align) and quest avatar (flex) align
--tgq-color-backdrop#00000080-
--tgq-color-accent#019ADAreward/button/icon etc.
--tgq-color-background#FAFAFA / #242424modal background color
--tgq-color-background-avatar#FFFFFF / #343434quest avatar container bacground color
--tgq-color-text#242424 / #FAFAFAtitle and description
--tgq-color-text-button#FFFFFF-
--tgq-shadow0px 4px 12px 0px #0000001Aquest 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"
}
CodeMessage
400 Bad RequestInvalid body
401 UnauthorizedThe 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"
}
CodeMessage
400 Bad RequestInvalid body
1.0.2

4 months ago

1.0.1

5 months ago

1.0.0

6 months ago

0.4.5

7 months ago

0.4.4

7 months ago

0.4.3

8 months ago

0.4.2

8 months ago

0.4.1

8 months ago

0.4.0

8 months ago

0.3.7

9 months ago

0.3.6

9 months ago

0.3.5

9 months ago

0.3.0

9 months ago

0.2.1

9 months ago

0.2.0

9 months ago

0.3.2

9 months ago

0.3.1

9 months ago

0.3.4

9 months ago

0.3.3

9 months ago

0.1.1

10 months ago

0.1.0

10 months ago