Embedding the portal in Telegram Mini Apps

Learn how to embed your Domino community portal within Telegram Mini Apps, handle authentication properly, and configure the necessary settings for seamless integration.

Prerequisites

You need a Domino account with a community created
Your portal must be set up and accessible at your-slug.domino.page
Basic understanding of Telegram Mini Apps development
Access to your Mini App's bot configuration

Overview

Telegram Mini Apps provide a seamless way to integrate web applications directly into the Telegram ecosystem. By embedding your Domino community portal in a Mini App, you can offer your Telegram community direct access to quests, leaderboards, and other community features without leaving the Telegram interface.

This integration requires special handling due to the unique authentication requirements and technical constraints of the Telegram Mini App environment. The portal automatically detects when it's running inside a Mini App and adjusts its behavior accordingly.

Understanding Telegram Mini App Authentication

Telegram Mini Apps have a unique authentication system that differs from standard web applications. When users access your Mini App, Telegram provides initialization data that must be forwarded to your portal for proper user identification and session management.

Key Authentication Concepts

Init Data: Telegram automatically generates user authentication data when the Mini App loads
URL Hash Fragment: Authentication data must be passed through the URL hash (#) for security
No SSR Parameter: Server-side rendering must be disabled for proper Mini App functionality
External Browser Flow: Social media connections require opening external browser windows

Telegram Mini Apps run in a sandboxed environment with limited browser capabilities. Social media authentication (Discord, Twitter) will open in external browser windows rather than inline popups.

Portal Configuration for Mini Apps

Before embedding your portal, you need to configure it properly in the Domino dashboard.

Setting Up Authentication Methods

Navigate to your portal settings and configure the authentication tab:

Access Portal Settings from your community dashboard
Go to the Authentication tab
Enable the social login methods your community needs:
- Discord: For Discord-based quests and verification
- Twitter: For Twitter engagement quests
Configure wallet login options if you have crypto-related quests

Bot ID Configuration

Your Telegram Mini App's bot must be configured in your portal settings to enable proper integration:

In your portal settings, navigate to the Authentication tab
Locate the Telegram Bot ID field
Enter your bot's unique identifier
Click Save to apply the configuration

This ensures the portal recognizes and properly handles requests from your specific bot, providing an additional layer of security.

The bot ID configuration helps the portal distinguish between legitimate Mini App requests and potential security threats, ensuring your community remains protected.

Basic Embedding Implementation

Here's the essential code structure for embedding your portal in a Telegram Mini App:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Community Portal</title>
</head>
<body>
    <iframe 
        width="100%" 
        height="100%" 
        id="domino-quests-iframe"
        frameborder="0">
    </iframe>
    
    <script>
    window.addEventListener("DOMContentLoaded", () => {
        const hash = location.hash;
        const iframe = document.querySelector('#domino-quests-iframe');
        iframe.src = "https://my-community.domino.page/quests?nossr=true" + hash;
    });
    </script>
</body>
</html>

Critical Parameters Explained

nossr=true: Disables server-side rendering, which is required for proper Mini App functionality
Hash forwarding: The location.hash contains Telegram's authentication data and must be passed to the portal

Expected Outcome

After implementing this code, your Telegram Mini App will display your Domino portal with proper authentication and full functionality. Users will be automatically signed in using their Telegram credentials.

Advanced Configuration Options

Custom Quest Targeting

You can embed specific quest pages or sections of your portal:

<script>
window.addEventListener("DOMContentLoaded", () => {
    const hash = location.hash;
    const iframe = document.querySelector('#domino-quests-iframe');
    
    // Embed a specific quest by ID
    iframe.src = "https://my-community.domino.page/quests/123?nossr=true" + hash;
    
    // Or embed the leaderboard
    // iframe.src = "https://my-community.domino.page/leaderboard?nossr=true" + hash;
});
</script>

Dynamic URL Construction

For more complex implementations, you can dynamically construct the portal URL based on user context:

window.addEventListener("DOMContentLoaded", () => {
    const hash = location.hash;
    const iframe = document.querySelector('#domino-quests-iframe');
    
    // Get user context from Telegram WebApp
    const userData = window.Telegram?.WebApp?.initDataUnsafe;
    
    // Construct portal URL with context
    let portalUrl = "https://my-community.domino.page/quests?nossr=true";
    
    // Add custom parameters based on user context
    if (userData?.user?.language_code) {
        portalUrl += `&lang=${userData.user.language_code}`;
    }
    
    iframe.src = portalUrl + hash;
});

Due to Telegram Mini App constraints, social media authentication flows (Discord, Twitter) will open in external browser windows rather than inline popups.

User Experience Flow

User clicks connect: Portal detects Mini App environment
External browser opens: Authentication happens in device's default browser
Return to Mini App: User manually returns to the Mini App after authentication
Automatic sync: Portal detects the new connection and updates the interface

Troubleshooting

Common Issues and Solutions

Portal not loading in Mini App

Verify the nossr=true parameter is included in your iframe URL
Check that the hash is being properly forwarded from location.hash
Ensure your bot ID is configured in portal settings under the Authentication tab
Confirm your portal URL is correct and accessible

Authentication failures

Confirm the portal URL is correct and accessible
Check for CORS issues if using custom domains
Ensure your bot ID matches exactly in the portal settings

Social connections not working

Ensure users understand the external browser flow
Verify social app configurations in your community settings
Test the authentication flow outside the Mini App first

PreviousAuthenticating users with the portal API NextLaunching a new Telegram Mini App for Domino Quests

Last updated 8 months ago

hashtagOverview

hashtagUnderstanding Telegram Mini App Authentication

hashtagKey Authentication Concepts

hashtagPortal Configuration for Mini Apps

hashtagSetting Up Authentication Methods

hashtagBot ID Configuration

hashtagBasic Embedding Implementation

hashtagCritical Parameters Explained

hashtagAdvanced Configuration Options

hashtagCustom Quest Targeting

hashtagDynamic URL Construction

hashtagHandling Social Media Connections

hashtagUser Experience Flow

hashtagTroubleshooting

hashtagCommon Issues and Solutions

Overview

Understanding Telegram Mini App Authentication

Key Authentication Concepts

Portal Configuration for Mini Apps

Setting Up Authentication Methods

Bot ID Configuration

Basic Embedding Implementation

Critical Parameters Explained

Advanced Configuration Options

Custom Quest Targeting

Dynamic URL Construction

Handling Social Media Connections

User Experience Flow

Troubleshooting

Common Issues and Solutions