Integrating claimr widget into Telegram mini app

Introduction

You can integrate the claimr widget into the Telegram Mini App. This setup allows you to leverage claimr's engagement features seamlessly within the Telegram environment, automatically utilizing the user's Telegram context.

This article demonstrates how to:

• Dynamically inject the claimr widget tailored for Telegram.

• Understand the interaction between the claimr widget and the Telegram Mini App API.

• Configure the required claimr campaign settings for Telegram integration.

Main files :

• src/claimr_wrapper.tsx: Handles claimr widget injection and configuration.

• src/example_app.tsx: Main UI component demonstrating Telegram API initialization.

Ensure you have the following installed:

• Node.js (v18+ recommended) – Install Node.js

• npm or yarn – Comes with Node.js (or install Yarn separately)

Running the project

Open a terminal and follow these steps:

1. Navigate to the project folder:

   cd path/to/claimr-tg-app-example

2. Install dependencies:

   Using npm:

   npm install

   Using Yarn:

   yarn

3. Start the development server:

   Using npm:

   npm start

   Using Yarn:

   yarn start

4. View in browser: The app will be available at: http://localhost:3000

Note: For full Telegram Mini App functionality testing, you'll need to run this within the Telegram environment.

Optional: Build for production

To create a production-ready build:

npm run build

or:

yarn build

This will create a build/ folder.

claimr Widget integration (claimr_wrapper.tsx)

The ClaimrWrapper component is responsible for dynamically injecting the claimr widget script into your application page.

Script Source

The widget script is loaded from: https://widgets.claimr.io/claimr.min.js

Script Attributes

It’s injected with the following custom attributes:

 script.setAttribute('data-container', CLAIMR_CONTAINER_ID);
 script.setAttribute('data-organization', 'claimr');
 script.setAttribute('data-campaign', 'telegram-mini-app');
 script.setAttribute('data-addons', 'sup,eap,eup,pvm,dcc');
 script.setAttribute('data-autoresize', 'true');
 script.setAttribute('data-platform', 'telegram');

Purpose of attributes:

This lets the widget know:

• where to render (container ID),

• which organization and campaign to load,

• which features (addons) to enable,

• and that it’s running in a Telegram context.

The wrapper ensures this script is injected only once per session.

Telegram mini app behavior (example_app.tsx)

This component demonstrates initializing the Telegram Mini App API to ensure the webview behaves correctly within Telegram:

useEffect(() => {
  window.Telegram?.WebApp?.expand();
  window.Telegram?.WebApp?.enableClosingConfirmation();
  window.Telegram?.WebApp?.disableVerticalSwipes();
}, []);

These standard Telegram Mini App API functions:

• expand(): Maximizes the Mini App window.

• enableClosingConfirmation(): Prompts the user before they close the Mini App.

• disableVerticalSwipes(): Prevents vertical swipes from accidentally closing or navigating away from the Mini App.

How it works (User view)

1. A Telegram user opens your Mini App containing the claimr integration.

2. The ClaimrWrapper injects the widget script with the data-platform='telegram' attribute.

3. The claimr widget initializes and reads the window.Telegram.WebApp context to automatically identify the Telegram user (using their Telegram ID and other available data).

4. The widget displays relevant tasks or quests based on the campaign configuration and the identified user.

5. If necessary for specific tasks, the widget might prompt the user to link other accounts (like Discord, email, or a wallet) through separate flows within the widget.

6. Task completions and results are synced back to claimr's backend, associated with the user's Telegram identity.

Campaign configuration: required settings

To ensure the claimr widget functions correctly within your Telegram Mini App and automatically recognizes users, specific campaign settings are required.

1. Navigate to Sign-in options:

   • Open your claimr dashboard.

   • Go to your specific campaign.

   • Click on Settings.

   • Select Sign-in options.

2. Set the following parameter:

   • Select sign-in services: Ensure that Telegram is selected in this field. This explicitly allows users to authenticate and interact with your campaign using their Telegram identity provided by the Mini App environment.