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.
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 securityNo 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.
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 functionalityHash forwarding: The
location.hashcontains 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
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=trueparameter is included in your iframe URLCheck that the hash is being properly forwarded from
location.hashEnsure 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
Last updated