Domino Docs
Go to Domino
  • Introduction
  • Concepts
  • Getting started
  • Quest Management
    • Creating your community on Domino
    • Launching your first quest
    • Creating custom quest tasks
  • Viewing quest claims (submissions)
  • Using custom rewards
  • Understanding the task verification automation
  • Restricting quest access to Discord role
  • Domino Portal
    • Setting up the portal
    • Customizing the portal
    • Managing portal quests
    • Creating leaderboards
  • Developer Resources
    • Authenticating users with the portal API
    • Embedding the portal in Telegram Mini Apps
  • Checking claim status
  • Getting quest modules
  • Claiming a quest
Powered by GitBook
On this page
  • 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
  1. Developer Resources

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.

PreviousAuthenticating users with the portal APINextChecking claim status

Last updated 4 days ago

Prerequisites

  • You need a Domino account with a

  • 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 , , 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.

Your Domino portal seamlessly embedded within a Telegram Mini App interface

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:

  1. Access Portal Settings from your community dashboard

  2. Go to the Authentication tab

  3. Enable the social login methods your community needs:

    • Discord: For Discord-based quests and verification

    • Twitter: For Twitter engagement quests

  4. 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:

  1. In your portal settings, navigate to the Authentication tab

  2. Locate the Telegram Bot ID field

  3. Enter your bot's unique identifier

  4. 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;
});

Handling Social Media Connections

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

  1. User clicks connect: Portal detects Mini App environment

  2. External browser opens: Authentication happens in device's default browser

  3. Return to Mini App: User manually returns to the Mini App after authentication

  4. 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

Configure authentication methods in your portal settings to support Mini App requirements
Add your Telegram bot ID in the portal settings to enable secure Mini App authentication
Social media connections open in external browser windows when accessed from Telegram Mini Apps
community created
quests
leaderboards