PlayableTrackingDeepLink

MRAID v3.0 playable ads framework with deep link tracking, analytics, and multi-network support

Complete framework for developing high-performance playable ads with MRAID v3.0, featuring deep link integration, comprehensive analytics, and support for major ad networks (AppLovin, Unity Ads, Google Ads, IronSource).

Table of Contents

• Features
• Quick Start
• API Endpoints
• Documentation
• MRAID v3.0 Support
• Project Structure
• Contributing
• License

Quick Start

Installation

# Clone repository
git clone https://github.com/The1Studio/PlayableTrackingDeepLink.git
cd PlayableTrackingDeepLink

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Setup database
npm run db:generate
npm run db:migrate

# Start development server
npm run dev

The server will start at http://localhost:3000

Your First API Request

Create a tracking link:

curl -X POST http://localhost:3000/api/v1/links \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "network": "applovin",
    "campaignId": "test-campaign-001",
    "storeUrlIos": "https://apps.apple.com/app/id123456789",
    "storeUrlAndroid": "https://play.google.com/store/apps/details?id=com.example.game"
  }'

Use the returned shortCode in your playable ad:

// In your playable ad
const trackingUrl = `https://your-domain.com/l/${shortCode}?playtime=30&score=150`;
document.getElementById('install-btn').onclick = () => {
  window.location.href = trackingUrl;
};

For detailed setup instructions, see Quick Start Guide

---

API Endpoints

Links Management

Method	Endpoint	Description	Auth
POST	/api/v1/links	Create new tracking link	✅
GET	/api/v1/links	List links with pagination	✅
GET	/api/v1/links/:id	Get link by ID	✅
GET	/api/v1/links/code/:shortCode	Get link by short code	✅

Click Tracking

Method	Endpoint	Description	Auth
GET	/l/:shortCode	Track click and redirect to store	❌
GET	/api/links/:linkId/clicks	Get clicks for link	✅
GET	/api/links/:linkId/stats	Get click statistics	✅

Analytics

Method	Endpoint	Description	Auth
GET	/api/v1/analytics	Get analytics for period	✅
GET	/api/v1/analytics/campaigns	Compare campaign performance	✅
GET	/api/v1/analytics/realtime	Get real-time metrics	✅
POST	/api/v1/analytics/cache/invalidate	Invalidate analytics cache	✅

For complete API documentation, see API Reference

---

Documentation

Getting Started

• Quick Start Guide - Get up and running in 10 minutes
• API Reference - Complete REST API documentation
• Integration Guide - Integrate with playable ads
• Deployment Guide - Production deployment instructions

MRAID v3.0 Reference

• Complete Documentation - Full MRAID v3.0 specification
• Key Concepts - Core architecture, DIP, states, viewability (16KB)
• Methods Reference - Complete API for 25+ methods (24KB)
• Events Reference - All events including v3.0 features (18KB)
• Quick Reference - Quick lookup guide with examples (17KB)

Total: 85KB of comprehensive MRAID v3.0 documentation

✨ Features

MRAID v3.0 Support

• ✅ exposureChange event - Real-time viewability measurement with percentage visible, occluded areas, geometric data
• ✅ audioVolumeChange event - Device volume monitoring and headphones detection
• ✅ getCurrentAppOrientation() - App orientation tracking
• ✅ unload() - Creative cleanup notification
• ✅ initVpaid() - VPAID integration support
• ✅ MRAID_ENV object - Pre-initialization environment detection

Deep Link Integration

• 🔗 App Store deep links (iOS & Android)
• 🔗 Universal Links & App Links
• 🔗 Custom URL schemes
• 🔗 Attribution tracking with UTM parameters
• 🔗 Campaign tracking integration

Analytics & Tracking

• 📊 Viewability tracking (MRC compliant)
• 📊 Engagement metrics (play time, completion rate, interactions)
• 📊 Audio state monitoring
• 📊 Conversion funnel tracking
• 📊 Multi-network analytics support
• 📊 A/B testing framework

Multi-Network Support

• 🎯 AppLovin MAX
• 🎯 Unity Ads
• 🎯 Google Ads
• 🎯 IronSource
• 🎯 Network-specific optimization

MRAID v3.0 Support

Basic Playable Ad Example

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
    <script src="mraid.js"></script>
</head>
<body>
    <div id="game-container">
        <!-- Your playable game -->
    </div>
    <button id="install-btn">Install Now!</button>

    <script>
        const storeUrls = {
            ios: 'https://apps.apple.com/app/id123456789',
            android: 'https://play.google.com/store/apps/details?id=com.yourapp.game'
        };

        function initAd() {
            console.log('MRAID Version:', mraid.getVersion());

            // Track viewability
            mraid.addEventListener('exposureChange', function(exposure) {
                if (exposure.exposedPercentage >= 50) {
                    console.log('Ad is viewable');
                }
            });

            // Track audio
            mraid.addEventListener('audioVolumeChange', function(volume) {
                console.log('Volume:', volume.volumePercentage);
            });

            // Install button
            document.getElementById('install-btn').onclick = function() {
                const platform = /iPhone|iPad/i.test(navigator.userAgent) ? 'ios' : 'android';
                mraid.open(storeUrls[platform]);
            };
        }

        if (mraid.getState() === 'loading') {
            mraid.addEventListener('ready', initAd);
        } else {
            initAd();
        }
    </script>
</body>
</html>

With Analytics

class PlayableAnalytics {
    constructor(config) {
        this.endpoint = config.analyticsEndpoint;
        this.sessionId = this.generateSessionId();
    }

    track(event, data) {
        navigator.sendBeacon(this.endpoint, JSON.stringify({
            event: event,
            sessionId: this.sessionId,
            timestamp: Date.now(),
            data: data
        }));
    }

    openStore(storeUrl) {
        this.track('store_opened', { url: storeUrl });
        mraid.open(storeUrl);
    }
}

const analytics = new PlayableAnalytics({
    analyticsEndpoint: 'https://analytics.yourserver.com/events'
});

// Track events
analytics.track('game_started');
analytics.track('level_complete', { level: 1, score: 100 });

// Open store with tracking
document.getElementById('install-btn').onclick = () => {
    analytics.openStore(storeUrl);
};

What's New in MRAID 3.0?

Major New Features

1. Enhanced Viewability - exposureChange event provides detailed exposure metrics
2. Audio Monitoring - audioVolumeChange tracks device audio state
3. VPAID Support - initVpaid() enables video ad integration
4. Better Environment Detection - MRAID_ENV object for early detection
5. App Orientation - getCurrentAppOrientation() for orientation tracking

Deprecated from v2.0

• ❌ getCurrentPosition() → Use exposureChange
• ❌ getScreenSize() → Use exposureChange
• ❌ getMaxSize() → Use exposureChange
• ❌ viewableChange event → Use exposureChange

See Migration Guide for details.

📊 Analytics Data Collection

What You Can Track

// Environment data
{
    mraidVersion: "3.0",
    platform: "ios",
    placementType: "inline",
    orientation: "portrait",
    features: { tel: true, sms: true, calendar: true }
}

// Viewability metrics
{
    exposedPercentage: 75.5,
    visibleRectangle: { x: 0, y: 100, width: 320, height: 200 },
    occlusionRectangles: [...]
}

// Audio metrics
{
    volumePercentage: 0.75,
    outputType: "headphones"
}

// Gameplay metrics
{
    playTime: 28.5,
    score: 150,
    completionRate: 0.68,
    interactions: 45
}

// Conversion metrics
{
    ctaClicked: true,
    storeOpened: true,
    installInitiated: true
}

See Analytics Guide for complete implementation.

🎯 Multi-Network Support

Network-Specific Packages

network-packages/
├── applovin/
│   ├── playable.html
│   └── config.json
├── unity/
│   ├── playable.html
│   └── config.json
├── google/
│   ├── playable.html
│   └── config.json
└── ironsource/
    ├── playable.html
    └── config.json

Network Requirements

Network	Max Size	MRAID	Audio	Orientation
AppLovin	5MB	v3.0	✅	Portrait
Unity Ads	5MB	v2.0+	✅	Both
Google Ads	5MB	v3.0	⚠️	Portrait
IronSource	5MB	v2.0+	✅	Portrait

🛠️ Development

Prerequisites

• Basic understanding of HTML5, JavaScript, CSS
• Familiarity with MRAID concepts
• Testing environment (MRAID-compatible SDK or simulator)

Testing

# Test in browser (with MRAID stub)
open index.html

# Test with network SDK
# Follow network-specific testing guides

Best Practices

1. File Size - Keep playables under 2MB for optimal performance
2. Load Time - Target < 3 seconds initial load
3. Frame Rate - Maintain 60 FPS for smooth gameplay
4. Audio - Respect device volume and mute state
5. Viewability - Start animations only when 50%+ visible
6. Testing - Test on real devices across iOS and Android

Project Structure

PlayableTrackingDeepLink/
├── src/
│   ├── controllers/           # Request handlers
│   ├── services/              # Business logic
│   ├── middleware/            # Express middleware
│   ├── routes/                # API routes
│   ├── utils/                 # Utilities
│   └── index.ts               # Application entry
├── prisma/
│   └── schema.prisma          # Database schema
├── docs/
│   ├── api-reference.md       # Complete API docs
│   ├── quick-start.md         # Getting started guide
│   ├── integration-guide.md   # Integration with playables
│   ├── deployment-guide.md    # Production deployment
│   └── mraid-v3/              # MRAID v3.0 documentation
│       ├── README.md
│       ├── 01-key-concepts.md
│       ├── 02-methods-reference.md
│       ├── 03-events-reference.md
│       └── 09-quick-reference.md
├── examples/                   # Example playable ads
├── templates/                  # Playable templates
├── network-packages/          # Network-specific builds
└── tools/                     # Build and optimization tools

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

Official Documentation

• IAB MRAID Guidelines
• MRAID v3.0 Specification (PDF)

Ad Networks

• AppLovin MAX Documentation
• Unity Ads Documentation
• Google Ads Documentation
• IronSource Documentation

Tools & Libraries

• MRAID Tester
• HTML5 Game Engines

🙋 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@the1studio.org

🌟 Acknowledgments

• IAB for the MRAID specification
• Ad network SDKs for implementation guidance
• Open source community for tools and libraries

---

Built with ❤️ by The1Studio

For more projects, visit The1Studio