Guides
Start typing to search…

Defining Application

Register your application code with TelemetryOS Studio to deploy to devices

Defining Application

After building your application code (typically using the CLI tool), you need to define it in TelemetryOS Studio to make it available for deployment to devices. This process connects your code repository to the TelemetryOS platform.

Prerequisites

Before defining your application in Studio, you should have:

  • ✅ Built your application code locally
  • ✅ Tested it with tos serve or equivalent development server
  • ✅ Created a telemetry.config.json configuration file
  • ✅ Pushed your code to a Git repository (GitHub recommended) or created a ZIP archive

Accessing Application Creation

Navigate to the application creation interface:

  1. Sign in to TelemetryOS Studio at app.telemetryos.com
  2. Select Content from the main menu
  3. Select Applications from the submenu
  4. Click the CREATE APPLICATION button

The application creation interface provides multiple methods for connecting your application code to the platform.

Application Definition Methods

TelemetryOS Studio provides three methods for defining applications:

1. Import GitHub Repository (Recommended)

Connect your GitHub repository for automated CI/CD deployment with version control integration.

Benefits:

  • Automatic builds on git push
  • Version history and rollback capability
  • Branch-based deployment (staging/production)
  • Team collaboration through pull requests
  • Continuous integration workflow

Setup:

  1. Push your application code to GitHub
  2. Select Import GitHub Repository in Studio
  3. Authorize TelemetryOS to access your GitHub account
  4. Select the repository and branch
  5. Configure build settings (usually auto-detected from telemetry.config.json)

Learn more: GitHub Integration

2. Import Git Repository

Connect any Git repository (GitLab, Bitbucket, self-hosted) using HTTPS URL.

Benefits:

  • Works with any Git hosting provider
  • Same CI/CD capabilities as GitHub integration
  • Version control and rollback
  • Supports private repositories with authentication

Setup:

  1. Push your application code to your Git provider
  2. Select Import Git Repository in Studio
  3. Enter repository HTTPS URL
  4. Provide authentication credentials if private
  5. Select branch for deployment
  6. Configure build settings

Learn more: Git Repositories

3. Upload Archive (ZIP)

Upload a pre-built ZIP file containing your application code.

Use cases:

  • Quick testing and prototyping
  • Internal applications without source control
  • Pre-built applications from third parties
  • Legacy applications or migrations

Setup:

  1. Build your application locally (npm run build)
  2. Create ZIP archive of the dist/ or build/ directory
  3. Select Upload Archive in Studio
  4. Upload the ZIP file
  5. Configure application metadata

Learn more: Upload a ZIP File

Required Configuration

Regardless of the method chosen, all applications require:

Application Metadata

Application Name

  • Unique identifier within your account
  • Used in SDK configure() call
  • Should match the name field in telemetry.config.json

Version

  • Semantic versioning recommended (e.g., 1.0.0)
  • Incremented with each deployment
  • Used for rollback and version management

Description (optional)

  • User-facing description of application functionality
  • Helps team members understand application purpose
  • Shown in application library

Source Configuration

Repository/Archive Location

  • GitHub repository URL or Git HTTPS URL
  • Branch name for Git-based deployments
  • ZIP file for archive uploads

Build Settings

  • Build command (e.g., npm run build, auto-detected from package.json)
  • Build output directory (e.g., dist/, auto-detected from telemetry.config.json)
  • Node.js version (if applicable)

Mount Points

Mount points are automatically detected from your telemetry.config.json:

{
  "name": "weather-dashboard",
  "version": "1.0.0",
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

These tell TelemetryOS where to load each component of your application:

  • render - Main display component shown on devices
  • settings - Configuration UI shown in Studio side panel
  • background - Worker scripts (optional)

Learn more: Mount Points

Application Definition Workflow

Step 1: Build Application Locally

Use the CLI to generate and develop your application:

# Generate new application
tos init weather-dashboard
cd weather-dashboard

# Develop and test locally
tos serve

# Build for production
npm run build

Step 2: Push to Repository

Commit and push your code:

git add .
git commit -m "Initial application build"
git remote add origin https://github.com/username/weather-dashboard.git
git push -u origin main

Step 3: Define in Studio

  1. Navigate to Content > Applications > CREATE APPLICATION
  2. Select Import GitHub Repository
  3. Authorize GitHub if not already connected
  4. Select repository: username/weather-dashboard
  5. Select branch: main
  6. Review auto-detected settings:
    • Name: weather-dashboard (from telemetry.config.json)
    • Build command: npm run build (from package.json)
    • Output directory: dist/ (from Vite config)
    • Mount points: /render, /settings (from telemetry.config.json)
  7. Click CREATE APPLICATION

Step 4: Initial Build

TelemetryOS automatically:

  1. Clones your repository
  2. Installs dependencies (npm install)
  3. Runs build command (npm run build)
  4. Packages application files
  5. Creates initial version (v1.0.0)

Build progress is shown in real-time. Build typically completes in 1-3 minutes.

Step 5: Add to Playlist

Once built, your application is ready for deployment:

  1. Navigate to Content > Playlists
  2. Open a playlist or create new one
  3. Add your application to a page
  4. Configure instance settings in side panel
  5. Assign playlist to devices or device groups
  6. Publish changes

Post-Definition Workflow

Continuous Deployment

With GitHub/Git integration, updates are automatic:

  1. Make code changes locally
  2. Test with tos serve
  3. Commit and push to repository
  4. TelemetryOS automatically builds new version
  5. New version available for deployment

Version Management

Studio provides version control:

  • View all published versions
  • Deploy specific versions to different device groups
  • Rollback to previous versions instantly
  • Compare versions and changes

Instance Configuration

Each application instance on a playlist can have unique settings:

  1. Add application to playlist page
  2. Click application in Studio page editor
  3. Settings component loads in side panel
  4. Configure instance-specific settings
  5. Settings saved to instance storage
  6. Different playlist instances can have different settings

Example: Same weather application showing different cities on different displays.

Application Types

Standard Applications

Most applications use the render + settings pattern:

  • Render displays content on devices
  • Settings provides configuration UI in Studio
  • Communicate via Storage API

Example structure:

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  }
}

Worker Applications

Applications needing continuous background processing:

  • Render displays content
  • Settings provides configuration
  • Worker runs continuously in background

Example use case: Data sync every 5 minutes, even when render not visible.

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings",
    "background": "/worker"
  }
}

Container Applications

Applications needing backend services:

  • Render displays content
  • Settings provides configuration
  • Containers run Docker services on device

Example use case: Local database or API server on device.

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"
  },
  "containers": [
    {
      "name": "api-server",
      "image": "myapp/api:latest",
      "port": 3000
    }
  ]
}

Common Definition Patterns

Development → Staging → Production

Use branches for different environments:

  1. Development - develop branch, auto-deploy to test devices
  2. Staging - staging branch, QA testing before production
  3. Production - main branch, deployed to production devices

Define three separate applications in Studio, each connected to different branch.

Monorepo with Multiple Applications

Single repository containing multiple applications:

monorepo/
├── apps/
│   ├── weather-dashboard/
│   ├── news-feed/
│   └── social-wall/
└── shared/

Define each application separately in Studio, pointing to same repository but different subdirectories.

Template-Based Applications

Create base template application, fork for customization:

  1. Define template application with generic functionality
  2. Fork repository for each customer/location
  3. Customize fork with specific branding/content
  4. Define forked version as new application in Studio

Security Considerations

Repository Access

Public repositories:

  • No authentication required
  • Code visible to anyone
  • Suitable for open-source applications

Private repositories:

  • Requires authentication (OAuth for GitHub, credentials for Git)
  • Code remains private
  • Recommended for proprietary applications

Build Security

TelemetryOS build process:

  • Runs in isolated container
  • No access to other customer code
  • Secrets/environment variables encrypted at rest
  • Build artifacts stored securely

Secrets Management

Never commit secrets to repository:

# ❌ DON'T DO THIS
const API_KEY = 'sk_live_abc123xyz';

Instead, use environment variables configured in Studio:

# ✅ DO THIS
const API_KEY = process.env.API_KEY;

Configure environment variables in Studio application settings.

Troubleshooting

Build Fails

Check build logs in Studio:

  • Dependency installation errors
  • TypeScript compilation errors
  • Build command failures
  • Missing files or configuration

Common fixes:

  • Ensure package.json scripts are correct
  • Verify telemetry.config.json is valid
  • Check that build outputs to correct directory
  • Ensure all dependencies are in package.json

Application Not Loading

Verify mount points:

  • Check telemetry.config.json mount point paths
  • Ensure built files exist at specified paths
  • Verify HTML files have correct structure

Check browser console:

  • SDK configuration errors
  • JavaScript runtime errors
  • Network request failures

Settings Not Appearing

Verify settings mount point:

{
  "mountPoints": {
    "render": "/render",
    "settings": "/settings"  // ← Must be defined
  }
}

Check settings component:

  • Calls configure() with correct app name
  • Renders without errors
  • Storage API calls are correct

Best Practices

1. Use Git-Based Deployment

Git integration provides the best development experience:

  • Version control out of the box
  • Automatic builds on push
  • Easy rollback and version management
  • Team collaboration support

2. Test Before Defining

Always test locally before defining in Studio:

tos serve  # Test locally first

3. Use Semantic Versioning

Follow semantic versioning for clarity:

  • 1.0.0 - Initial release
  • 1.1.0 - New features, backward compatible
  • 2.0.0 - Breaking changes

4. Document Configuration

Add README to repository explaining:

  • What the application does
  • Required settings/configuration
  • Environment variables needed
  • How to test locally

5. Environment-Based Branches

Use branches for different deployment environments:

  • main → Production devices
  • staging → Testing devices
  • develop → Development devices

6. Monitor Build Times

Optimize build for faster deployments:

  • Minimize dependencies
  • Use caching where possible
  • Optimize asset sizes
  • Consider build output size

Next Steps

After defining your application in Studio:

  1. Add to Playlist - Deploy to devices
  2. Configure Settings - Instance configuration
  3. GitHub Integration - Set up automated deployment
  4. Storage Methods - Learn data persistence
  5. Local Development - Advanced development workflow

Learn More

Updated 5 days ago

What’s Next