How Hyperstone Works

This page explains the core concepts behind Hyperstone and how the platform optimizes your app’s configuration in real time. You don’t need a background in machine learning to use Hyperstone — but understanding these fundamentals will help you set up better optimizations and interpret your results.

The Big Picture

When a user opens your app, Hyperstone delivers a configuration to your app — a set of parameter values chosen by the optimization algorithm. As the user interacts with your app, your app then reports measurements back to the platform. The algorithm uses these measurements to learn which configurations lead to better outcomes, and serves improved configurations to subsequent users.

flowchart
    Hyperstone[Hyperstone] -->|1. Delivers Configuration| App[Your App]
    App -->|2. Affects Experience| User((User))
    User -.->|3. Generates Events| App
    App -->|4. Sends Measurements| Hyperstone

This loop runs continuously. The more users interact with your app, the more data the algorithm collects, and the better it gets at finding the optimal configuration.

Key Concepts

Parameters

Parameters are the configuration values that Hyperstone optimizes. Each parameter has a name and a set of possible values that you define.

Think of parameters as the “knobs” you want the system to tune. Examples for a mobile game:

Parameter	Possible Values
n_lives	1, 2, 3, 5
ad_cooldown_seconds	30, 60, 120, 300
show_ads_after_death	true, false
starting_coins	0, 50, 100, 500
difficulty	easy, normal, hard

A specific combination of parameter values is called a configuration. For example:

n_lives: 3
ad_cooldown_seconds: 60
show_ads_after_death: true
starting_coins: 100
difficulty: normal

Hyperstone’s job is to find the configuration — out of all possible combinations — that maximizes your target metric.

Tip

Start with parameters that you believe have the most impact on your target metric. You can always add more later as the system learns.

Metrics and Measurements

Measurements are the raw signals your app sends to Hyperstone. Each measurement has a name and a numeric value. Measurements accumulate over time for each user.

Examples of measurements:

• ad_revenue: 0.03 (user watched an ad worth $0.03)
• levels_completed: 1 (user completed one level)
• session_time_minutes: 12.5 (user spent 12.5 minutes in the app)

Metrics are calculated indicators derived from accumulated measurements. A metric combines one or more measurements using a formula to produce a meaningful business indicator.

For example, the metric ARPU (Average Revenue per User) might be calculated as:

ARPU = Total Revenue / Number of Users

Where Total Revenue and Number of Users are aggregated measurements. Some metrics are built-in (like session count, retention, and engagement time), while others you define as custom metrics specific to your app.

Target Metric

The target metric is the metric you want Hyperstone to maximize. It defines the “goal” of the optimization.

Common target metrics include:

• Ad Revenue per User — maximize how much ad revenue each user generates
• Retention Day 7 — maximize the percentage of users who return after 7 days
• Session Count — maximize how many sessions users have
• LTV — maximize lifetime value

The choice of target metric shapes which configurations the algorithm favors. For example, optimizing for ad revenue might favor more frequent ad placements, while optimizing for retention might favor a smoother, less interrupted experience. The algorithm’s job is to find the balance within your parameter space that best serves the chosen goal.

Caution

You can only set one target metric per optimization. Choose the metric that most closely aligns with your business objective.

Labels

Labels are optional metadata attached to measurements. They have low cardinality (a small number of distinct values) and help Hyperstone segment and aggregate data.

For example, an ad impression measurement might include labels like:

• ad_network: "admob"
• ad_format: "rewarded"

Labels let the system break down metrics by dimension without creating separate measurement types for every combination.

The Algorithm: Multi-Armed Bandit

At its core, Hyperstone models the optimization problem as a Multi-Armed Bandit (MAB).

The Analogy

Imagine you’re standing in front of a row of slot machines (the “bandits”), each with a different, unknown payout rate. Your goal: maximize your total winnings over many plays. You need to balance exploration (trying machines you know less about) with exploitation (playing the machine that has paid out best so far).

In Hyperstone’s context:

• Each arm is a possible configuration (a combination of parameter values)
• Each pull is a user receiving that configuration
• The reward is the target metric value observed for that user

How It Works in Practice

1. Exploration phase — When an optimization starts, the algorithm has no data. It generates diverse configurations to explore the parameter space broadly and gather initial information about which configurations perform well.

2. Learning — As measurements come in, the algorithm builds a statistical model of each configuration’s performance. It tracks not just the average outcome, but also the uncertainty — how confident it is in that estimate.

3. Exploitation with continued exploration — The algorithm increasingly favors configurations that have shown strong results, but it never stops exploring entirely. It assigns more users to promising configurations while still occasionally trying alternatives, in case a better option exists.

4. Convergence — Over time, the algorithm converges on high-performing configurations. The longer it runs and the more data it collects, the more confident and accurate its choices become.

Why Not Just A/B Test?

The key advantage of the MAB approach over traditional A/B testing is that it starts improving outcomes immediately rather than waiting for a test to conclude. In an A/B test, half your users are stuck with the control variant for the entire test duration. In MAB-based optimization, the algorithm dynamically shifts traffic toward better-performing configurations as soon as it has enough signal — so every user benefits from what the system has learned so far.

Additionally, MAB naturally handles:

• Many parameters at once — no need to test them one at a time
• Changing conditions — the algorithm can adapt if user behavior shifts
• No manual decision-making — no analyst needed to decide when to stop and which variant “won”

What Happens Under the Hood

Here is the complete sequence of events between the Hyperstone server, the SDK in your app, and your users:

sequenceDiagram
    actor User
    participant App as Your App
    participant SDK as Hyperstone SDK
    participant Server as Hyperstone Server

    Note over User, Server: 1. Get Configuration
    User->>App: Opens app
    App->>SDK: Initialize
    SDK->>Server: Request Config
    Server->>Server: Generate optimal config
    Server-->>SDK: Config values
    SDK-->>App: Deliver Config
    App->>App: Apply settings<br/>(e.g., lives, ads)

    Note over User, Server: 2. Feedback Loop
    User->>App: Plays, creates events
    App->>SDK: Log events
    SDK->>SDK: Buffer measurements
    SDK->>Server: Batch send
    Server->>Server: Update algorithm model

Here’s a step-by-step walkthrough of a single optimization cycle:

1. A new user opens your app. The SDK calls the Hyperstone API to request a configuration.

2. The server generates a configuration. The optimization algorithm — based on everything it has learned so far — selects a configuration for this user. It might be the current best-performer, or an alternative it wants to explore.

3. The configuration is delivered to the SDK. The SDK provides this configuration to your app via a callback. Your app applies the values (e.g., setting difficulty to “hard”, giving 3 lives, showing ads every 60 seconds).

4. The user interacts with your app. As they play, watch ads, make purchases, or trigger custom events, the SDK tracks these as measurements.

5. Measurements are sent to the server. The SDK batches and sends accumulated measurements to the Hyperstone backend. These are associated with the configuration that user received.

6. The algorithm updates. The server records the new data and refines its understanding of how well that configuration performs. This updated knowledge influences what configuration the next user will receive.

This cycle repeats for every user, thousands or millions of times, with the algorithm getting incrementally smarter with each interaction.

Summary

Concept	What It Is
Parameter	A configurable value in your app (e.g., n_lives, ad_cooldown) with defined possible values
Configuration	A specific combination of parameter values assigned to a user
Measurement	A raw numeric signal sent from your app (e.g., ad_revenue: 0.03)
Metric	A calculated indicator derived from measurements (e.g., LTV = Revenue / Users)
Target Metric	The metric the algorithm tries to maximize
Label	Low-cardinality metadata attached to measurements for segmentation
Optimization	The continuous process of finding the best configuration for your target metric
Algorithm (MAB)	The statistical method used to balance exploration and exploitation

Next Steps

Now that you understand how Hyperstone works, see what you need to get started:

→ Quick Start & Setup