# Helium Docs > Helium is a remote paywall platform for iOS, Android, React Native and Flutter apps: design and edit paywalls without app updates, run A/B tests and targeting, add Stripe or Paddle web checkout (App2Web), and track revenue. These docs cover the mobile SDKs, the dashboard, web checkout, testing and rollout, revenue tracking and analytics forwarding, the Data Access API, and the Helium MCP server. > ## Agent Instructions > Helium is a paywall platform for mobile apps. Paywalls, workflows, triggers, targeting and experiments are configured in the dashboard (https://app.tryhelium.com); the SDK's job is to initialize, present a paywall for a trigger, and report purchases. > Pick the SDK page for the user's platform: /sdk/quickstart-ios (Swift), /sdk/quickstart-android (Kotlin), /sdk/quickstart-react-native, /sdk/quickstart-flutter. Method names differ per platform; copy them from the page for that platform, never from another platform's page. > Pages under /sdk/quickstart-ios-v3 and /sdk/quickstart-android-v0 are legacy SDK versions. Use them only when the user is on that version; for upgrades use the /migrations pages. > For live dashboard data (paywalls, workflows, metrics) connect the Helium MCP server at https://app.tryhelium.com/api/mcp (see /ai-tools/mcp). For SQL over events, revenue, subscriptions and users use the Data Access API (/data-access/overview) and the helium-data-access skill (/data-access/agent-skill). This documentation site also exposes a docs-search MCP server at https://docs.tryhelium.com/mcp. > Web checkout (App2Web) with Stripe or Paddle is a separate flow from in-app purchases; start at /web-checkout/overview. > Every page is available as Markdown by appending .md to its URL. The full index is at https://docs.tryhelium.com/llms.txt. # Helium for AI agents Source: https://docs.tryhelium.com/ai-tools/agents How Claude, Cursor, Codex and other AI tools can read these docs, query your Helium dashboard, and investigate your data: MCP servers, agent skills, llms.txt and Markdown pages. Helium exposes everything an AI agent needs to integrate the SDK, debug a paywall, or answer questions about your data. Use this page to pick the right interface. ## Which interface to use | You want to... | Use | | :- | :- | | Read or search these docs from an agent | [Docs as Markdown](#docs-as-markdown) or the [docs search MCP](#docs-search-mcp) | | Ask about your paywalls, workflows, triggers, experiments and metrics | [Helium MCP server](/ai-tools/mcp) | | Run SQL over your events, revenue, subscriptions and users | [Data Access API](/data-access/overview) with the [`helium-data-access` skill](/data-access/agent-skill) | | Integrate the Helium SDK into an app | The quickstart for your platform: [iOS](/sdk/quickstart-ios), [Android](/sdk/quickstart-android), [React Native](/sdk/quickstart-react-native), [Flutter](/sdk/quickstart-flutter) | ## Docs as Markdown Every page on this site is available as plain Markdown. Append `.md` to any URL, or send `Accept: text/markdown`: ```bash theme={null} curl -L https://docs.tryhelium.com/sdk/quickstart-ios.md curl -L -H "Accept: text/markdown" https://docs.tryhelium.com/sdk/quickstart-ios ``` Site-wide indexes: * [`/llms.txt`](https://docs.tryhelium.com/llms.txt): every page with a one-line description. Start here. * [`/llms-full.txt`](https://docs.tryhelium.com/llms-full.txt): the full content of every page in one file. Agent instructions for these docs are included at the top of `llms.txt` and of every `.md` page. ## Docs search MCP The docs site hosts an MCP server that searches this documentation. It needs no login. ```text theme={null} https://docs.tryhelium.com/mcp ``` Use it when an agent needs grounded answers about Helium's SDKs or dashboard. For your organization's live data, use the Helium MCP server below instead. ## Helium MCP server The [Helium MCP server](/ai-tools/mcp) at `https://app.tryhelium.com/api/mcp` gives an agent a read-only view of your dashboard: paywalls, workflows, triggers, targeting, experiments and metrics, plus docs search. Sign-in happens in the browser when the client first connects. ## Agent skills Skills are installable instruction packs for coding agents such as Claude Code, Codex and Cursor. * [`helium-data-access`](/data-access/agent-skill): how to answer questions about your Helium data with the Data Access API: which tables to use, which filters to always apply, and recipes for common investigations. ```bash theme={null} npx skills add cloudcaptainai/docs --skill helium-data-access ``` Skills are also published at [`/.well-known/agent-skills/index.json`](https://docs.tryhelium.com/.well-known/agent-skills/index.json) for tools that discover skills automatically. ## Discovery endpoints Agents that support them can find all of the above from the site root: | Endpoint | Contents | | :- | :- | | `/.well-known/mcp/server-card.json` | Docs search MCP server card | | `/.well-known/agent-card.json` | Agent card for this site | | `/.well-known/agent-skills/index.json` | Skills index | | `/llms.txt`, `/llms-full.txt` | Page indexes | # Helium MCP Server Source: https://docs.tryhelium.com/ai-tools/mcp Connect Claude, ChatGPT, Cursor and other AI tools to your Helium dashboard data. The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is a standard for connecting AI tools to external systems. The Helium MCP server gives your AI tool a read-only view of your Helium organization: paywalls, workflows, triggers, targeting, experiments, metrics, and these docs. Ask questions like "which paywall is live on my onboarding trigger?" or "how did trial starts move last week?" and the tool answers from your real dashboard data. > [!NOTE] > > The Helium MCP server is read-only. It cannot edit, publish, or delete anything in your organization. ## Connect The server URL is the same for every client: ```text theme={null} https://app.tryhelium.com/api/mcp ``` There are no API keys to copy. When your client connects for the first time it opens the Helium login page in your browser. Sign in, choose the organization you want to connect, approve the permissions, and you are done. Pick your client: Client Any other client that supports remote MCP servers with OAuth works the same way: give it the URL above and sign in when prompted. ## Permissions During sign-in your client asks for these permissions. Each one unlocks the tools listed in [Available tools](#available-tools) below; a tool you have not granted returns a message telling you which permission to add. | Permission | What it unlocks | | - | - | | `org:read` | Who you are and which organization is connected | | `paywalls:read` | Paywalls, their versions, source code, previews and publish history | | `workflows:read` | Workflows, triggers and targeting | | `experiments:read` | Experiments and their variants | Metrics and documentation tools are available to every connection. Everything is scoped to the organization you picked at sign-in. To switch organizations, disconnect the server in your client and connect again. ## Available tools ### Paywalls | Tool | What it returns | | - | - | | `list_paywalls` | Your paywalls, newest first, with optional name search | | `get_paywall` | One paywall with the products, product buckets and live version it serves, plus its web paywall link | | `get_paywall_preview` | The preview image of a paywall | | `list_paywall_versions` | The saved versions of a paywall | | `list_paywall_publish_history` | Publish and rollback history of a paywall | | `get_paywall_version_code` | The source of one file in a paywall version | | `diff_paywall_versions` | A diff of one file between two versions | | `find_paywall_usage` | Every workflow, trigger and experiment a paywall appears in | ### Workflows, triggers and targeting | Tool | What it returns | | - | - | | `list_workflows` | Your workflows with their triggers and targeting rules | | `get_workflow` | One workflow with each rule's audience, paywall or experiment | | `list_triggers` | Your triggers and the workflow each one belongs to | | `list_targeting` | Your saved targeting definitions | | `get_targeting` | One targeting definition and its rule | ### Experiments | Tool | What it returns | | - | - | | `list_experiments` | Your experiments with their variants and traffic split | | `get_experiment` | One experiment and the workflows and triggers it is wired into | | `get_experiment_metrics` | Per-variant time series for one experiment page metric, with the All Sources / Paywall Variant toggle and filters | | `check_experiment_health` | Whether an experiment can declare a winner: verdict, significance per decision metric, users needed per arm and days remaining | ### Metrics | Tool | What it returns | | - | - | | `list_metrics` | Every dashboard metric with a one-line description | | `explain_metric` | The full definition of one metric and the filters it accepts | | `get_metrics` | Time series for up to a few metrics with the dashboard's defaults | ### Docs and account | Tool | What it returns | | - | - | | `search_docs` | Search results from docs.tryhelium.com | | `get_doc` | A full documentation page | | `whoami` | The signed-in user and connected organization | ## Good to know A few things the tools report exactly as the SDK sees them, which can differ from what a paywall's edit view shows: * A paywall's products, product buckets and content come from its **published version**. A paywall that has never been published is not served anywhere. * A trigger with no workflow attached shows no paywall. * Targeting rules are evaluated top to bottom and the first matching rule wins. A rule can point at a paywall, at an experiment, or at "show no paywall". * An experiment serves only while a workflow rule points at it and it is not stopped. Its start and end dates are labels, not a schedule. * Variant percentages that do not add up to 100 are scaled so that they do. ## Security * The server is read-only and can only see the organization you connected. There are no tools that change anything. * Your client stores a token for the connection; Helium does not store it. Remove the connection from your client to stop access. * Treat tool output like any other data you paste into a chat: paywall names and descriptions are your own content, but review before sharing a transcript outside your team. ## Troubleshooting * **"This tool needs the paywalls:read permission"**: reconnect the server and approve all permissions on the consent screen. * **Sign-in loops or 401 errors**: remove the server from your client and add it again; the stored token may belong to an organization you no longer have access to. * **Tool results are cut off**: list tools are paged. Ask for the next page or narrow with a name search. * **Your client does not show the newest tools**: claude.ai and Claude Code cache the tool list. Refresh the Helium server in your client's connector settings, then start a new chat. # How it works Source: https://docs.tryhelium.com/background/how-it-works How a paywall experiment runs in Helium end to end and how to plan your first experiments. ## Overview Our editor stack uses HTML/CSS to build customizable and performant paywalls that you can edit in seconds. **Here's how it works:** * Use our visual editor to create any paywall. You can add components from the layout tab, or drag right from the blocks tab onto the editor. * Add pre-created components like buttons and product selectors, or create your own. Upload your own fonts or images from the assets page, and add your own button interactions and subscribe actions on the right tab. * Once your paywall is saved, Helium will optimize the HTML/CSS and bundle it to be ready for remote fetching and rendering. * When a user opens their app and you call **`initialize`** the paywall will be fetched down. We've heavily optimized our serving infrastructure to get to an average latency of around 75ms. * Assets like fonts and images will then be cached to reduce latency further on the next app opens. * Then, when you decide to **`triggerUpsell`** the paywall will display immediately. Because we preload all assets there is generally no loading time. * Any actions the user takes with the paywall are translated with our SDK, leading to virtually no incremental delays on actions like opening bottomsheets, switching plans, or subscribing. * We've extensively tested our paywalls and shown them to convert just as well as native paywalls \[and even better once you run your first tests ;)]. We're always happy to work together to run a comparison test to prove it out. * Once your paywalls are implemented, now you'll be able to run tests in just minutes instead of days! Get growing! ## **How to plan your paywall experiments** Here's our suggestion on how to experiment on your paywalls: ### 1. Presentations If your users rarely see the paywall, all other optimizations are moot. Aim for at least 80% of weekly active users (WAU) to encounter it. The easiest way to do that is just shop pop-ups on app open, but those tend to be low conversion. The best way to drive high-conversion paywall presentations is to encourage users to engage with "Premium" or "Gated" functionality that leads them to a paywall — pique their curiosity get them excited about what they'll get with premium. * **Add new entrypoints:** Find opportunities to encourage people to "try" your premium features. It's often effective to add paywall entrypoints that would lead directly to the Premium functionality. E.g. if one of your premium features lets you "Talk with an AI coach", don't make the entrypoint "Buy premium to talk to AI", instead find a natural place to add a CTA "Get best practices from a virtual coach" that leads to your paywall. * **Add a paywall in onboarding**: You should *always* add a paywall in onboarding as this generally accounts for well over >50% of conversions for most apps. This can seem scary as it's before users have seen your app, but is generally the moment of maximum intent and maximum volume. * **Add a persistent Premium CTA**: Often users are curious about premium, and you want to make it extremely low effort for them to discover your subscription. Often this is best achieved through a persistent, always-viewable CTA. This could be a top-banner, a bottom tab item, or a pinned item in a feed. Generally apps pair this with an option to upgrade in settings or profile. * **Announce relevant features**: If you add new premium features, consider adding banners, modals, or cards to advertise the new feature and drive users into the paywall flow. *** ### 2. Trials Free trials can significantly reduce purchase friction by letting users taste the benefits risk-free. * **Trial Length Variations** : 3-day vs. 7-day vs. 14-day: Test which length results in the best balance between user trust and eventual paid conversion. * **Onboarding Trial Offer**: Prompt new users to start a free trial after they see a key use case of your app. * **Reminder & Transparency**: Test sending reminders before a trial ends, clearly stating when billing will begin. *** ### 3. Pricing and Plans Choosing the right pricing structure has a huge impact on LTV and monthly recurring revenue. * **Begin with 2–3 Durations**: Example: Monthly, Annual, and possibly weekly. * **Test prices**: Start by testing drastically different price values (e.g. 2.99 and 11.99) to triangulate the tradeoff between LTV and conversion. Realize that higher prices will generally have lower trial to paid conversion and retention. * **Price annual as a premium on monthly LTV**: Longer duration will tend to be more valuable, and you'll often want to discount it down to slightly above your LTV on the shorter plans. E.g. if your monthly plan costs 6.99 and your average retention is 4.5 months, your LTV is around 31.46 (ignoring re-subscribes). You may consider pricing the annual offering at \~\$49.99, which is about a 40% discount from 12 months of the monthly rate, but still >50% higher LTV than your monthly plan. * **Plan differentiation**: Once you have solid traction on your initial plans, consider adding higher-tier plans to take advantage of populations with higher willingness to pay. *** ### 4. Product Display How you frame your plans can be just as important as the price itself. * **Plan Highlights**: Test showing the number of plans you show, plan naming, and how you present the plans. Generally two stacked full-width product offerings work best, but all apps vary. * **Uniform Pricing Units**: Show all prices in weekly terms or highlight the monthly equivalent of the annual plan. E.g. * Monthly: 3.99/mo * Yearly: 2.99/mo (billed as \$36 yearly) * **Default Selection**: Pre-select your preferred plan, but keep toggling simple for a user-friendly experience. *** ### 5. General Display A paywall's layout and messaging should clearly convey why your premium is worth it. * **Core Benefits**: Test different hero value propositions and highlighted features * **Layout & Hierarchy**: Use design elements (color, icons) to draw attention to the primary action and top value plan. * **Exit styles**: Test different exit CTAs, including location (top left corner, top right corner, bottom). Often text can work better than "X's" — E.g. "Skip", "I don't want this") * **Social Proof**: Display testimonials, ratings, or user counts to add credibility. * **Purchase CTA**: Generally less committal CTAs ("Start trial", "Try now", "Continue") work better than more committal CTAs ("Buy now", "Subscribe") *** ### 6. Discounting Discounts can boost conversions but should be used strategically to avoid diluting perceived value. * **Exit Discounts**: Offer a discount when a user tries to close the paywall. * **Win-Back Discounts**: Send targeted offers to users who have canceled or shown signs of churn. * **Time-Limited Promotions**: Create urgency with a countdown timer or "limited time" messaging. *** ### 7. Personalization Tailoring paywalls to various user segments lets you fine-tune pricing and messaging. This is often some of the most valuable testing you can run, but also the hardest. This is where Helium's SmartSelect algorithm can help. * **Cohort-Based**: High-intent power users vs. casual users may respond differently to certain price points or offers. * **Geo-Specific**: Adjust pricing based on region to match local purchasing power. * **Behavioral Triggers**: Offer different discounts or highlight different premium features based on past in-app actions. Good luck and get growing! # Agent skill Source: https://docs.tryhelium.com/data-access/agent-skill Give Claude Code, Codex, Cursor and other AI agents a skill for investigating your Helium data with the Data Access API. The Helium Data Access skill teaches your AI agent how to answer questions about your Helium data the right way: which tables to use, which filters to always apply, how to handle late data, and step-by-step recipes for common investigations. It uses the [Data Access API](/data-access/overview), so you need a Data Access secret key. ## Install Run this in your project: ```bash theme={null} npx skills add cloudcaptainai/docs --skill helium-data-access ``` Choose your agent when asked. Add `-g` to install it for all your projects. To update it later, run `npx skills update helium-data-access`. > [accordion] Install without npx > > Copy the skill folder from GitHub into your agent's skills folder. For Claude Code, use `.claude/skills`. For Codex, use `.agents/skills`. > > ```bash theme={null} > git clone --depth 1 https://github.com/cloudcaptainai/docs.git /tmp/helium-docs > mkdir -p .claude/skills > cp -R /tmp/helium-docs/skills/helium-data-access .claude/skills/ > rm -rf /tmp/helium-docs > ``` > > Or [view the skill on GitHub](https://github.com/cloudcaptainai/docs/tree/main/skills/helium-data-access) and copy `SKILL.md` and the `references` folder by hand. ## Set your secret key Create a secret key in **Settings → Data Access** (see [Turn it on](/data-access/overview#turn-it-on)), then make it available to your agent as `HELIUM_SECRET_KEY`: ```bash theme={null} export HELIUM_SECRET_KEY="your-secret-key" ``` The skill tells your agent never to print or store the key. Keep it out of your repository. ## Ask questions Ask your agent in plain language. It picks the skill when the question is about your Helium data. For example: * "Why did revenue drop last week compared to the week before?" * "Which variant is winning in my onboarding paywall experiment?" * "What's our trial-to-paid conversion rate by product for the last 90 days?" * "Where do users drop off on the paywall for the onboarding trigger?" The agent answers with the numbers, the time window and filters it used, the SQL it ran, and any caveats such as recent data still arriving. ## What's included * **Rules for every query:** always filter on time, count events and users without duplicates, leave out test purchases, account for late data, and use attribution correctly. * **Investigation recipes:** * **Revenue changed:** confirm the change, split it by event type and segment, and rule out missing store data. * **Experiment results:** check the variant split, then compare conversion and revenue per variant. * **Trial conversion:** conversion by trial start week and segment, and time to first payment. * **Paywall funnel:** drop-off from open to purchase, render failures, fallback paywalls and purchase errors. The skill is read-only, like the Data Access API. For questions about your paywalls, workflows and experiment setup, also connect the [Helium MCP server](/ai-tools/mcp). # Schema changelog Source: https://docs.tryhelium.com/data-access/changelog Changes to the Data Access schemas. Helium only adds columns to a released schema. Removing or renaming a column, or changing what it means, ships as a new schema version (for example `customer_v2`). The older version keeps working for a deprecation period, announced on this page when the new version is released. **customer_v1** Initial release * Added the `events`, `revenue`, `subscriptions` and `users` views. See [the schema reference](/data-access/schema). # Data Access API Source: https://docs.tryhelium.com/data-access/overview Query your organization's Helium events, revenue, subscriptions and users with SQL. > [!WARNING] > > Data Access is in private beta. If you don't see **Data Access** in **Settings**, ask your Helium contact to turn it on for your organization. The Data Access API lets you run read-only SQL against your Helium data. Use it to load Helium data into your warehouse, build your own reports, or join paywall activity with your own product data. Every query runs against the [`customer_v1` schema](/data-access/schema). Each query only ever sees your organization's rows, whatever SQL you send. ## Turn it on 1. In the Helium dashboard, open **Settings** and scroll to **Data Access**. Only organization Admins see this section. 2. Enter a name for your secret key and click **Create secret key**. Copy the key right away: it is shown only once. > [!NOTE] > > Your Data Access secret key is not the Helium API key you use in your app's SDK setup. The API key cannot query data, and the secret key does not work in the SDK. Keep the secret key on your server: never put it in an app, a website or a public repository. ## Send a query Send a `POST` request with your secret key as a bearer token and the SQL in the body: ```bash theme={null} curl -X POST https://app.tryhelium.com/api/metrics-query \ -H "Authorization: Bearer $HELIUM_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"sql": "SELECT event_name, count() AS events FROM events WHERE event_timestamp > now() - INTERVAL 7 DAY GROUP BY event_name ORDER BY events DESC"}' ``` Queries use [ClickHouse SQL](https://clickhouse.com/docs/sql-reference). Table names resolve to `customer_v1`, so `events` and `customer_v1.events` are the same table. A successful response is ClickHouse JSON: ```json theme={null} { "meta": [{ "name": "event_name", "type": "String" }, { "name": "events", "type": "UInt64" }], "data": [{ "event_name": "experience_opened", "events": "18234" }], "rows": 1, "statistics": { "elapsed": 0.041, "rows_read": 52110, "bytes_read": 1834211 } } ``` 64-bit integers come back as strings so they keep full precision. Every response has an `X-Request-Id` header. Include it when you contact support about a query. ## Secret keys * Secret keys belong to your organization, not to the person who created them. Admins can see and revoke every key in **Settings → Data Access**. * A key expires 30 days after it was last used. Each day you use it, the 30 days start over, so a key in regular use does not expire. * A revoked key stops working within a minute. * Revoking your last key turns off Data Access for your organization. Create a new key to turn it back on. * Only Data Access secret keys work with this API. Your Helium API key and other keys do not. ## Data freshness Data Access is not real-time. Data reaches Helium over time from your users' devices and from the app stores, so the most recent hours are incomplete and recent numbers can still change. | Table | When new data shows up | What arrives late | | - | - | - | | `events` | Seconds after the event reaches Helium. | Devices send events in batches and hold them while offline. About 5% of events reach Helium more than an hour after they happened, about 1.5% more than a day after, and a few more than a week after. | | `revenue` | Seconds after the store notifies Helium. | Stores send notifications on their own schedule. Most arrive within a few minutes, but some arrive hours or days later. Refunds often arrive weeks or months after the purchase. | | `subscriptions` | Rebuilt every 15 minutes, so up to about 20 minutes behind `revenue`. | Totals, status and `has_access` change as renewals, cancellations and refunds arrive. | | `users` | Seconds after new events reach Helium. | Counts and `latest_*` columns change as late events arrive. | To keep a copy of this data up to date: * **events:** `event_timestamp` is the time on the user's device, and Helium doesn't expose when it received an event. Each time you sync, reload the last 7 days and upsert on `event_id`, which also removes the rare duplicate events. Events that arrive more than 7 days late are missed this way, so also reload the last 30 days about once a week. * **revenue:** `timestamp` is when Helium received the store notification. Each time you sync, reload rows from a day before your last sync and upsert on `notification_id`, so rows that become visible slightly late are not missed. * **subscriptions** and **users:** reload rows with a `last_updated` from a day before your last sync, and upsert on `subscription_id` and `helium_persistent_id`. Numbers here can differ slightly from the Helium dashboard for the same period, because the dashboard and your query may read the data at different times. ## Limits | Limit | Value | | - | - | | Query run time | 300 seconds | | Data read per query | 20 GB | | Memory per query | 8 GB | | Rows returned per query | 1,000,000 | | Response size per query | 4 MB | | Queries running at once | 4 per organization | | SQL length | 100,000 characters | Queries are read-only. You cannot change these limits from your query. The 4 MB response limit is usually reached long before 1,000,000 rows. A day of `events` with every column is often tens of MB, so export in pages: select only the columns you need, sort on the time column and the row ID, and start each page after the last row of the previous one. ```sql theme={null} SELECT event_id, event_timestamp, event_name, helium_persistent_id, trigger_name, paywall_name FROM events WHERE event_timestamp >= '2026-11-01' AND event_timestamp < '2026-11-02' AND (event_timestamp, event_id) > (toDateTime64('LAST_EVENT_TIMESTAMP', 3), 'LAST_EVENT_ID') ORDER BY event_timestamp, event_id LIMIT 10000 ``` Leave out the `(event_timestamp, event_id)` line for the first page. Stop when a page returns fewer rows than the `LIMIT`. If a page returns `RESULT_TOO_LARGE`, lower the `LIMIT`. Page `revenue` the same way on `timestamp` and `notification_id`. ## Errors Errors return a JSON body with a type and a message: ```json theme={null} { "error": { "type": "TOO_MANY_BYTES", "message": "Limit for rows or bytes to read exceeded..." } } ``` | Status | When | What to do | | - | - | - | | `400` | Invalid request body, or invalid SQL (for example `SYNTAX_ERROR`, `UNKNOWN_IDENTIFIER`). | Fix the request or query. | | `401` | Missing, expired or revoked secret key, or a key that is not a Data Access secret key. | Create a new secret key in **Settings → Data Access**. | | `403` | Data Access isn't turned on for your organization during the private beta. | Ask your Helium contact to turn it on. | | `422` | The query hit a limit: `TIMEOUT_EXCEEDED`, `TOO_MANY_BYTES`, `TOO_MANY_ROWS`, `TOO_MANY_ROWS_OR_BYTES`, `MEMORY_LIMIT_EXCEEDED`, or `RESULT_TOO_LARGE` for a response over 4 MB. | Narrow the date range, select fewer columns, aggregate, or add a `LIMIT`. | | `423` | Your organization's Helium access is locked, for example by an unpaid invoice. | Contact your Helium account manager. | | `429` | Four of your queries are already running. | Wait for one to finish, then retry. | | `502` | The query failed on Helium's side (`QUERY_FAILED` or `UPSTREAM_ERROR`). | Retry later. Contact support with the `X-Request-Id` if it keeps happening. | | `503` | Helium couldn't check your key or load your organization's settings (`AUTH_UNAVAILABLE` or `SERVICE_UNAVAILABLE`). Your key is still valid. | Retry after a few seconds. | ## Data use and privacy * Queries can only read your organization's data. Other organizations' data is never visible, and you cannot read Helium's internal tables. * For each query, Helium records the time, the key used, the SQL, the status, how long it took and how much data it read, to run and debug the service. Helium does not store your results. * Helium leaves out IP addresses, emails and other contact details. See [Personal data](/data-access/schema#personal-data). Your data still includes personal data about your app's users, such as device IDs, user IDs and location. You are responsible for handling the data you export in line with your own privacy policy and the law that applies to you. # customer_v1 schema Source: https://docs.tryhelium.com/data-access/schema Tables and columns you can query with the Data Access API. `customer_v1` has four tables. Each one only returns your organization's rows, and each has an `organization_id` column with your organization's ID. New columns may be added to `customer_v1` at any time, so select columns by name instead of relying on `SELECT *` column order. Removing or renaming a column, or changing what it means, only happens in a new schema version. See the [schema changelog](/data-access/changelog). ## Personal data Helium leaves out direct contact details: * IP addresses and network provider fields are not included. * Email addresses in text and ID columns are replaced with `[redacted]`. * `custom_user_traits_json`, `attributed_custom_traits_json`, `latest_custom_traits_json` and `latest_rc_subscriber_attributes_json` drop keys for names, emails, phone numbers, IP addresses, postal addresses, birth dates, advertising IDs and ad click IDs (for example `email`, `firstName`, `phone`, `fbclid`). Other keys are returned as sent. ## events One row per SDK event from your apps. This is the same event stream described in [Helium events](/guides/helium-events). `event_name` uses the same names as analytics forwarding. Only these events are included: | `event_name` | Meaning | | - | - | | `initialization_failed` | The SDK could not download your paywalls | | `experience_opened`, `experience_open_failed` | A paywall was presented, or failed to present (see `open_failure_reason`) | | `experience_view_rendered`, `experience_view_render_failed` | The paywall finished rendering, or failed to | | `experience_skipped`, `experience_dismissed`, `experience_view_closed` | The paywall was skipped by targeting, dismissed, or closed | | `purchase_started`, `purchase_pending`, `purchase_succeeded`, `purchase_failed`, `purchase_abandoned` | Purchase flow | | `entitlement_restored`, `entitlement_restore_failed` | Restore purchases | | `user_experiment_allocated` | The user was assigned to an experiment variant | | `custom_event` | A custom paywall action (see `custom_paywall_action_name`) | Not included: successful SDK setup and paywall downloads, attempts to open a paywall that was already on screen, and internal events such as web checkout modals and consent prompts. Some columns are normalized so the same value is always spelled the same way: * **`app_environment`:** upper case, for example `PRODUCTION`, `SANDBOX` or `DEBUG`. Empty when the SDK didn't send it. * **`device_idiom`:** `phone`, `tablet`, `tv`, `car`, `mac`, `vision` or `unknown`. * **`device_orientation`:** `portrait`, `portrait_upside_down`, `landscape_left`, `landscape_right`, `face_up`, `face_down` or `unknown`. * **`locale_code`:** a language tag such as `en-US`, or just the language (`en`) when the device didn't report a region. Columns: * **Event:** `event_id`, `event_name`, `event_timestamp`, `error_description`, `open_failure_reason` * **User and session:** `user_id`, `helium_persistent_id`, `helium_device_id`, `helium_session_id`, `paywall_session_id`, `revenuecat_app_user_id`, `custom_user_traits_json` * **Paywall:** `trigger_name`, `paywall_id`, `paywall_name`, `paywall_presentation_type`, `is_fallback`, `is_second_try`, `custom_paywall_action_name`, `custom_paywall_action_params` * **Experiment:** `experiment_id`, `experiment_name`, `experiment_type`, `experiment_user_bucket`, `experiment_chosen_variant_id`, `experiment_chosen_variant_name`, `experiment_chosen_variant_type` * **Purchase:** `product_id`, `storekit_transaction_id`, `storekit_original_transaction_id`, `app_transaction_id`, `google_play_order_id`, `google_play_purchase_token`, `canonical_transaction_id`, `attribution_token`, `currency_code` * **App and device:** `app_bundle_id`, `app_display_name`, `app_version`, `app_build`, `app_environment`, `helium_sdk_version`, `platform`, `os_name`, `os_version`, `device_manufacturer`, `device_model`, `device_idiom`, `device_orientation`, `screen_width_points`, `screen_height_points`, `screen_width_pixels`, `screen_height_pixels`, `is_system_dark_mode` * **Location and locale:** `geo_country_name`, `geo_continent_code`, `geo_continent_name`, `geo_region_name`, `geo_region_code`, `geo_city`, `locale_language`, `locale_code`, `locale_country` > [!NOTE] > > A very small number of events can appear twice with the same `event_id`, about 1 in 1,000 rows. It's rare, but you still need to deduplicate on `event_id` for exact counts: count with `uniqExact(event_id)` instead of `count()`, or upsert on `event_id` when you copy rows into your warehouse. ## revenue One row per store revenue event (purchase, renewal, refund and so on) from the App Store, Google Play, Stripe, Paddle or RevenueCat. A store notification delivered more than once appears once: rows with the same transaction, `event_type`, event time and amount are counted once. Repeated real events, such as a cancellation, resubscribe and second cancellation, each keep their own row. Each store sends different fields, so many `revenue` columns are empty for some stores. Only stores you have connected to Helium appear. * **Test purchases:** `environment` is upper case: `PRODUCTION`, or `SANDBOX` for test purchases. A few rows have it empty. Stripe test mode can be a large share of Stripe rows. Add `WHERE environment = 'PRODUCTION'` for revenue numbers. * **Zero amounts:** `revenue_usd` and `revenue_local` are `0` on rows without a charge, such as cancellations, expirations and free trial starts. That is most rows. * **Proceeds:** `proceeds_usd` and `proceeds_local` are Helium's estimate of what you keep after store commission and sales tax. They are negative on refunds. On Stripe refunds they equal the full refund amount. For App Store, Google Play and RevenueCat rows from before 22 June 2026, proceeds are `0` because Helium did not record them yet. Stripe and Paddle rows have proceeds for all dates. * **`event_timestamp`:** empty for some Stripe rows. Use `coalesce(event_timestamp, timestamp)`. * **Store-specific columns:** `recent_subscription_start_date` is empty for RevenueCat. `storefront` is empty for Paddle and often for Stripe. `offer_id` and `offer_code` are mostly empty outside Google Play. * **`product_type`:** `auto_renewable_subscription`, `non_renewing_subscription`, `consumable`, `non_consumable` or `one_time` (a one-off Stripe or Paddle purchase). `NULL` when the store doesn't send it, which is common for RevenueCat. * **User columns:** `revenuecat_app_user_id` is filled in only for RevenueCat and some Stripe and Paddle rows. `idfv` comes only from RevenueCat on iOS. `app_account_token` is filled in only when your app sets one at purchase. * **`helium_persistent_id`:** often empty. It is always empty for App Store Server Notifications and Google Play notifications. To link revenue to paywalls and experiments, join `revenue.original_transaction_id` to `subscriptions.subscription_id` and use the `attributed_*` columns. Columns: * **Event:** `notification_id`, `event_type`, `timestamp`, `event_timestamp`, `store_notification_type`, `store_notification_subtype`, `source`, `app_store`, `environment` * **Transaction:** `transaction_id`, `original_transaction_id`, `app_transaction_id`, `app_account_token`, `quantity`, `family_shared` * **Money:** `revenue_usd`, `proceeds_usd`, `revenue_local`, `proceeds_local`, `currency`, `storefront` * **Product and offer:** `product_id`, `product_type`, `subscription_group_id`, `renewal_date`, `recent_subscription_start_date`, `offer_id`, `offer_type`, `offer_code`, `ios_offer_type`, `ios_offer_period` * **User:** `revenuecat_app_user_id`, `idfv`, `helium_persistent_id` ## subscriptions One row per subscription or purchase, with its revenue to date and the paywall, experiment and variant it is attributed to. `has_access` is `1` when the subscription currently grants access: it has a renewal date in the future or a pending trial, and its latest event is not a refund, revocation or expiration. Use `has_access` instead of `subscription_status` to count active subscribers. `subscription_status` only changes when a store event arrives, so it can lag behind. `is_trial_pending` is `1` until a trial is both at least 7 days old and at least 2 days past its `trial_end_timestamp`, so it stays `1` for 7 days even on a 3-day trial. `is_trial_resolved` is its opposite. To find trials whose end date has passed, filter on `trial_end_timestamp < now()`. For trial-to-paid conversion rates, use `is_trial_resolved = 1`, because it waits 2 extra days for the store to report whether the trial converted. The `attributed_*` columns are filled in only when Helium can link the subscription to a paywall session from the SDK, and `is_helium_attributed` is `1` for those rows. Purchases Helium cannot link to a paywall session have no attribution, and their `attributed_*` text columns hold `Unknown`. `attributed_experiment_id` is also `Unknown` on attributed rows that weren't part of an experiment, so filter with `NOT IN ('', 'Unknown')`. Revenue totals cover the subscription's whole life to date: * **`net_revenue_usd`:** gross charges minus refunds, before store fees. It equals `sum(revenue_usd)` over the subscription's rows in `revenue`. `total_revenue_usd` holds the same value. * **`net_proceeds_usd`:** what you keep after store commission, sales tax and refunds. It equals `sum(proceeds_usd)` over the same rows, so it has the same gap before 22 June 2026 for App Store, Google Play and RevenueCat. * **`total_refund_amount_usd`:** the refunded amount, as a negative number. Some timestamp columns use a placeholder date instead of being empty when something never happened: * **`2299-12-31`:** `trial_start_timestamp` when there was no trial, and `first_paid_timestamp` when the subscription was never paid. To find trials, use `trial_start_timestamp < '2200-01-01'`. To count paid subscriptions, use `has_paid_revenue = 1`. * **`1970-01-01`:** `last_renewal_timestamp`, `last_cancellation_timestamp`, `expiration_timestamp`, `conversion_timestamp` and `event_timestamp` when there is no such event. `trial_end_timestamp` is either `1970-01-01` or `2299-12-31` when there was no trial, and `2299-12-31` for about 2% of trials whose end date is unknown. Use `trial_start_timestamp`, not `trial_end_timestamp`, to tell whether there was a trial. * **Empty:** `latest_subscription_start_date` and `latest_renewal_date` are `NULL` when unknown. Columns: * **Subscription:** `subscription_id`, `product_id`, `product_type`, `store`, `webhook_source`, `environment`, `storefront`, `currency`, `family_shareable`, `has_access`, `subscription_status` * **Lifecycle:** `trial_start_timestamp`, `trial_end_timestamp`, `is_trial_pending`, `is_trial_resolved`, `first_paid_timestamp`, `conversion_timestamp`, `conversion_type`, `last_renewal_timestamp`, `latest_renewal_date`, `latest_subscription_start_date`, `last_cancellation_timestamp`, `expiration_timestamp`, `first_event_type`, `latest_event_type`, `first_revenue_event_type`, `transaction_type`, `earliest_revenue_event_timestamp`, `latest_revenue_event_timestamp`, `last_updated` * **Revenue:** `total_revenue_usd`, `net_revenue_usd`, `net_proceeds_usd`, `num_payments`, `renewal_count`, `has_paid_revenue`, `has_refund`, `num_refunds`, `total_refund_amount_usd` * **Offer:** `offer_type`, `offer_id`, `store_offer_id`, `event_offer_id` * **User:** `rc_app_user_id`, `rc_app_id`, `app_transaction_id`, `app_account_id`, `idfv`, `helium_persistent_id`, `helium_session_id`, `app_session_id`, `attributed_user_id`, `user_country` * **Attribution:** `is_helium_attributed`, `attributed_paywall_id`, `attributed_paywall_name`, `attributed_paywall_template_name`, `attributed_paywall_session_id`, `attributed_trigger_name`, `attributed_experiment_id`, `attributed_experiment_name`, `attributed_experiment_type`, `attributed_experiment_audience_id`, `attributed_variant_allocation_id`, `attributed_variant_allocation_name`, `attributed_custom_traits_json`, `attributed_event_store_transaction_id`, `attributed_event_app_transaction_id` * **Attributed SDK event:** `event_timestamp`, `event_is_fallback`, `event_product_id`, `event_app_build`, `event_app_name`, `event_os_name`, `event_sdk_version`, `event_device_type`, `event_device_model`, `event_country`, `event_city`, `event_environment` ## users One row per Helium user (`helium_persistent_id`), with their latest device details and lifetime counts. Columns: * **Identity:** `helium_persistent_id`, `observed_user_ids`, `observed_rc_user_ids`, `observed_app_attribution_tokens`, `observed_transaction_ids`, `canonical_rc_app_user_id`, `canonical_app_attribution_token` * **Activity:** `first_seen_timestamp`, `last_seen_timestamp`, `num_sessions`, `num_paywall_sessions`, `num_paywall_opens`, `num_conversions`, `last_updated` * **Firsts:** `first_paywall_seen`, `first_paywall_seen_timestamp`, `first_experiment_allocated`, `first_experiment_allocated_timestamp`, `first_product_purchased`, `first_product_purchased_timestamp` * **Latest device:** `latest_country`, `latest_city`, `latest_app_store`, `latest_app_name`, `latest_device_build`, `latest_device_model`, `latest_device_type`, `latest_sdk_version`, `latest_environment` * **Attributes:** `latest_custom_traits_json`, `latest_rc_subscriber_attributes_json` ## Example queries Paywall conversion by trigger over the last 30 days: ```sql theme={null} SELECT trigger_name, uniqExactIf(event_id, event_name = 'experience_opened') AS opens, uniqExactIf(event_id, event_name = 'purchase_succeeded') AS purchases, round(purchases / nullIf(opens, 0), 4) AS conversion_rate FROM events WHERE event_timestamp > now() - INTERVAL 30 DAY AND app_environment NOT IN ('SANDBOX', 'DEBUG') GROUP BY trigger_name ORDER BY opens DESC ``` Active subscribers and lifetime net revenue by experiment variant: ```sql theme={null} SELECT attributed_experiment_name, attributed_variant_allocation_name, countIf(has_access = 1) AS active_subscribers, round(sum(net_revenue_usd), 2) AS net_revenue_usd, round(sum(net_proceeds_usd), 2) AS net_proceeds_usd FROM subscriptions WHERE attributed_experiment_id NOT IN ('', 'Unknown') AND environment = 'PRODUCTION' GROUP BY attributed_experiment_name, attributed_variant_allocation_name ORDER BY attributed_experiment_name, net_revenue_usd DESC ``` Daily production revenue for the last 14 days: ```sql theme={null} SELECT toDate(timestamp) AS day, round(sum(revenue_usd), 2) AS revenue_usd FROM revenue WHERE timestamp > now() - INTERVAL 14 DAY AND environment = 'PRODUCTION' GROUP BY day ORDER BY day ``` # Introduction Source: https://docs.tryhelium.com/getting-started/introduction What Helium is and what it does: remotely editable paywalls, A/B testing and targeting, web checkout and revenue analytics for iOS, Android, React Native and Flutter apps. ## App monetization for the AI era Helium helps you launch paywall experiments in minutes to boost in-app revenue. ## What is Helium? > [card] Remote Control > > Edit paywalls instantly without app updates > [card] A/B Testing > > Run experiments to find what converts best > [card] AI Optimization > > Let AI continuously improve your conversion > [card] Analytics > > Track performance with detailed insights ## How It Works **1. Onboarding** Migrate your existing paywall or create a new one **2. Visual Editing** Use the Helium visual editor to change UI, add pages, modify products, add discounting, and more **3. Experimentation** Run personalization experiments to automatically discover what drives conversion and incremental revenue # Quickstart Source: https://docs.tryhelium.com/getting-started/quickstart Go from a new Helium account to a live paywall: connect products, build a paywall, create a workflow and trigger, integrate the SDK, connect revenue webhooks and launch. This quickstart shows you how to set up, preview, and go live with an AI-editable Helium paywall in your app. ## Create your account on Helium Create your Helium account at [app.tryhelium.com](https://app.tryhelium.com). This will take you to the **Helium dashboard**, where you can create paywalls, manage api keys and integrations, run A/B tests, view analytics, and more. ## Connect your products Visit [Integrations → Products](https://app.tryhelium.com/integrations/products) and sync your products from the App Store and/or Google Play store. ## Create a new paywall 1. Click on the **Paywalls** tab in the sidebar (or go [here](https://app.tryhelium.com/paywalls)). 2. Click **New Paywall** and complete that flow > [!NOTE] > > You can swap products in and out as desired. Just remember to have your products linked in the paywall before going live! ## Create a workflow and trigger(s) Once you have published a pawyall, visit [Workflows](https://app.tryhelium.com/workflows) to create your first workflow. Once created, add a **trigger**. **Triggers** are what you use in your app to determine which workflow (and its associated paywall/s) to show to a user. A **workflow** is a configuration of trigger(s) that should point to the same paywall, or that share the same targeting or experimentation setup. ## Install and set up the SDK Choose your mobile platform and follow the integration quickstart: > [card] [iOS](/sdk/quickstart-ios) > > Swift/SwiftUI/UIKit > [card] [Android](/sdk/quickstart-android) > > Kotlin/Jetpack Compose > [card] [React Native](/sdk/quickstart-react-native) > > React Native/Expo > [card] [Flutter](/sdk/quickstart-flutter) > > Flutter integration ## Set up revenue reporting Follow our [guide on revenue reporting](https://docs.tryhelium.com/guides/revenue-reporting) to connect Helium to your app's revenue events via webhooks. > [!TIP] > > Revenue reporting enables Helium to provide detailed analytics about your app's monetization. It's a *must* to get the most out of Helium! ## Set up fallbacks to guarantee 100% paywall uptime for your users Follow our [guide on fallbacks](https://docs.tryhelium.com/guides/fallback-bundle) to guarantee that you'll have 100% uptime of your paywalls even if a user doesn't have a network connection. ## Pre-launch and go live! Before going live, here's a quick checklist. As always, reach out via your Helium slack channel or to [founders@tryhelium.com](mailto:founders@tryhelium.com) if you'd like any help with testing. ### Testing Checklist * Paywall created with products * Workflow + trigger created * SDK set up and paywall displays * Purchases can be completed from your paywall(s) * [Fallbacks](/guides/fallback-bundle) are configured 🎉 Congratulations! You now have a live Helium paywall and are ready to take your app's monetization to new heights! # Connect Analytics and MMPs Source: https://docs.tryhelium.com/guides/analytics-forwarding Forward Helium paywall events and subscription activity to your analytics provider from the dashboard, with user, product, paywall and experiment details on each event. ## Forward Helium events 1. Open [Integrations > Analytics](https://app.tryhelium.com/integrations/analytics) and select a provider. 2. Name the integration, enter the requested credentials, and select **Save Configuration**. 3. Complete a purchase. Find the test user's events in your provider; batches can take a few minutes. | Provider | What you'll need | | - | - | | Mixpanel | Project ID, project token, and service-account credentials. Match **Simplified Identity Merge** to your project. | | Amplitude | API key and matching US/EU data residency. | | PostHog | Project token and instance address. | | Statsig | Server secret key. | Helium forwards paywall views, purchase attempts, and successes server-to-server, with user, product, paywall, and experiment context. [Event reference](/guides/third-party-analytics#what-events-and-properties-are-logged). In Mixpanel, build an `experience_opened` to `purchase_succeeded` funnel, grouped by `experiment_chosen_variant_id`. ## Match events to users Use the same user ID in Helium and your provider. For anonymous users, pass the provider's anonymous/device ID to Helium. [Identity setup](/guides/third-party-analytics#linking-%26-identifying-users). ## Send conversions to Meta Once Helium events arrive in your analytics provider, connect its outbound destination: * **PostHog:** open **Data pipeline > Destinations > Meta Ads Conversions**, add your Pixel ID and access token, then select your conversion events. [Setup](https://posthog.com/docs/cdp/destinations/meta-ads). * **Amplitude:** open **Data > Catalog > Destinations > Meta Pixel**, add your Pixel ID and access token, map events and user identifiers, then enable the sync. [Setup](https://amplitude.com/docs/data/destination-catalog/meta-pixel). * **Mixpanel:** its [Facebook Ads integration](https://mixpanel.com/partners/integrations/facebook-ads) syncs cohorts for audience targeting, not purchase events. For conversion reporting, use your server or CDP's Meta connection. * **Statsig:** enable an [outgoing event webhook](https://docs.statsig.com/integrations/event_webhook#outgoing) to your server or CDP, which maps the events to Meta's Conversions API. Map trial starts separately from paid purchases, include the destination's required identifiers, and check a test conversion in Meta. Deduplicate if you also report the same event client-side. ## Other MMPs and renewals Forward Helium's [purchase-success event](/guides/helium-events#paywall-and-purchase-events) through your existing MMP SDK or server integration. Client-side delivery requires the app to receive the result and doesn't cover renewals. For renewals without an app open, connect billing-provider webhooks to your MMP through your backend or a supported service. Already using RevenueCat? Its [MMP integrations](https://www.revenuecat.com/docs/integrations/attribution) are another option; follow the destination's identifier and billing-source requirements. Other destinations? [Contact Helium](mailto:founders@tryhelium.com). # How to view experimental traits in Amplitude Source: https://docs.tryhelium.com/guides/analytics-providers Configure Helium to send paywall events and experimental data to your analytics provider You can configure Helium to automatically send paywall events to your analytics provider of choice. Here are the steps: ## Amplitude 1. Go to [app.tryhelium.com/integrations](https://app.tryhelium.com/integrations). Click **Amplitude** 2. Give your integration a name. Enter your API key (you can find it under **Settings** > **Projects** > **\[Your Project Name]** and grab an API key from there) That's it! Paywall events (see [Helium Events](/guides/helium-events)) will now come into Amplitude, prefixed with `helium_` ![Events in Amplitude](https://mintcdn.com/helium/pu7f_tWG0y8Xd9IH/images/analytics/guide-events.png?fit=max\&auto=format\&n=pu7f_tWG0y8Xd9IH\&q=85\&s=8cbc879a7f76082719e2f0baf2f8ebb4) ## Viewing Experimental Properties Besides a boatload of other event properties, if a Helium paywall was seen as part of an experiment, it will come with a number of experimentation-focused properties that may be useful for analysis in Amplitude. Helium experiments work by separating out paywalls into *allocations*. These are numbers that sum to 100, and represent the percentage of users who will see each paywall. For example, in an A/B test between 2 paywalls with 90% of people in control and 10% in test, then the allocations will be \[90, 10]. To determine which group a user falls into, we hash a uniformly random id associated with the user, and use that to randomly place them into one of the two groups. For example: * Let's say the allocations are \[90, 10] as above (90% control paywall, 10% test) * Helium will assign my user a random **userPercentage** between 1 and 100 inclusive * If this value is between \[1, 90] inclusive, then the user will be placed in the control group. If the user percentage is in \[91, 100], then the user will fall in the test group Helium then uses this data to compute experimental metrics like revenue lift, conversion lift, and more. We log these experimentation properties to help you with your analysis. These are currently prefixed with `additionalPaywallFields`: ![Analytics Fields](https://mintcdn.com/helium/pu7f_tWG0y8Xd9IH/images/analytics/guide-analytics-fields.png?fit=max\&auto=format\&n=pu7f_tWG0y8Xd9IH\&q=85\&s=84cbd80521ea622f984d72147e9ffd62) > [!NOTE] > > We'll avoid deprecating these properties, but we might continue to evolve Helium's logging to provide cleaner groups of event names in the future. Reach out to us if you have any specific requirements in your experimentation monitoring! ### Experimental Properties Reference > [!NOTE] > > As of SDK v3.0+, experiment data is sent in a structured `experimentInfo` object. See the [3rd Party Analytics Integration Guide](/guides/third-party-analytics) for complete field reference. **Current Structure (v3.0+):** The `experimentInfo` object contains: * `experimentId`, `experimentName`, `experimentType` - Experiment metadata * `chosenVariantDetails` - Which variant the user saw * `hashDetails` - User bucketing information * `audienceId`, `audienceData` - Targeting criteria * `allocationMetadata` - Custom metadata from dashboard See [complete field reference](/guides/helium-events#experimentinfo-structure) for details. **Legacy Fields (v2.x, deprecated):** | Field Name | Description | Type | | - | - | - | | `allocations` | Array of allocation percentages | array\[int] | | `chosen_allocation` | Bucket index (0-based) | int | | `experimentName` | Experiment name | string | | `userPercentage` | User hash bucket (1-100) | int | For Mixpanel, PostHog, Statsig, and current Amplitude setup, see [Connect analytics and MMPs](/guides/analytics-forwarding). # App2Web FAQ Source: https://docs.tryhelium.com/guides/app2web-faq Paywalls, attribution, experiments, and entitlements with Paddle. [Paddle integration](/guides/paddle-onboarding-guide) / [Go-live checklist](/guides/app2web-go-live-checklist). > [accordion] How do I add web products to my paywall? > > It's pretty simple: once you've synced your web products, add them to a standard paywall and link a simple hosted web paywall. A **purchase action on a web product** opens that web paywall in the browser. > > When the user subscribes or dismisses the web paywall, Helium takes them back into your app. > > [Here's the full paywall-building guide](/guides/build-app2web-paywall). > [accordion] How do I test my App2Web paywall in my app? > > Follow the [on-device testing guide](/guides/paywall-previews#app2web-previews) to test App2Web using Helium’s triple-tap flow. > [accordion] How do I test that entitlements are granted correctly? > > We recommend starting with [App2Web previews](/guides/paywall-previews#app2web-previews). Use a real purchase on an [eligible US device](/guides/app2web-previews#purchase-eligibility) to test entitlement delivery; simulated purchases don't charge you or grant entitlements. > > Then make a real purchase through your app's trigger and check that access unlocks when you return. See the [Paddle tests](/guides/paddle-onboarding-guide#7-test-everything). > > You can use [Paddle's webhook simulator](https://developer.paddle.com/webhooks/simulator/test-webhooks/) to test delivery separately; it doesn't create a real purchase. > > **Using RevenueCat? Also check that:** > > * Paddle webhooks reach RevenueCat for the correct user. > * Web products grant the right entitlement tier. > * Paddle and [RevenueCat webhooks](/guides/revenue-reporting#2-revenuecat-webhooks) reach Helium as configured, and the purchase appears there. > [accordion] Do I need to change my MMP or analytics integration? > > We recommend [analytics forwarding](https://app.tryhelium.com/integrations/analytics) for supported analytics destinations: manage your connections in one place, and let Helium forward events with user, product, paywall, and experiment details. > > Already tracking Helium's purchase-success events? That still works when users return to your app. StoreKit-only tracking won't capture web purchases. > > Once your events arrive, you can forward conversions to Meta through destinations such as PostHog or Amplitude. Our setup guide covers each provider and other MMP routes. > > [Here's how to connect your analytics provider or MMP](/guides/analytics-forwarding). > [accordion] What will customers see in the web paywall? > > We make the browser experience look as similar to your app as possible. Your hosted paywall opens in a browser, with `clickthrough.to` visible in the address bar. After checkout, users return to your app. > > **Payment sheet:** we’ve optimized the payment sheet to keep checkout simple. Here’s what users will see: > > * **Price:** we calculate it from the selected offer. Free trials show \$0.00 due today in USD; paid trials show the initial charge. > * **Names:** make both product and price names customer-facing. We recommend leaving dollar amounts out; checkout already shows the price. Paddle's Apple Pay title uses the product name. > [accordion] What should my sales tax settings be? > > We recommend Paddle’s [automatic regional tax pricing](https://developer.paddle.com/changelog/2025/default-automatic-tax-setting/), which adds sales tax to US purchases where applicable. > [accordion] What will users see when they cancel their subscription? > > Your **Manage Subscription** button takes users to the [Paddle customer portal](https://developer.paddle.com/build/customers/integrate-customer-portal/). If they [cancel at the end of the billing period](https://developer.paddle.com/build/subscriptions/cancel-subscriptions/), they keep access until then. > [accordion] Which email is used for cancellation, retention, and win-back emails? > > The **billing email captured by Paddle at checkout** is used for cancellation, retention, and win-back emails. With Apple Pay, this comes from the user’s Apple Pay billing information, so **you don’t need to collect an email in your app**. It may differ from their app login email. > [accordion] How do I roll out App2Web? > > 1. **Create both audiences:** one with the **Paddle eligibility preset** AND `user_id_bucket <= 10`, and one with **just the Paddle eligibility preset**. > 2. Select the smaller audience and launch a **50/50 experiment: your current IAP paywall versus App2Web**. > 3. Monitor conversion rates and checkout/access issues for **24 hours**. > 4. If the data looks good, use the same experiment and change its audience to the full eligible audience. > > See the [rollout steps](/guides/paddle-onboarding-guide#8-roll-out-your-experiment). > [accordion] How should I evaluate an App2Web experiment? > > **Start with conversion rate:** compare trial starts or direct purchases per exposed user. This is your early signal that the flow is working and users are converting. > > **Once trials have converted and enough paid-purchase data is in, evaluate take-home ARPU:** revenue after fees, taxes, and refunds, divided by all exposed users. Compare cohorts of the same age so both variants have had the same time to convert and generate revenue. For offers without trials, wait for enough paid purchases to make a meaningful comparison. > > Check confidence intervals before calling a winner; a conversion count alone does not establish significance. > > **Proceeds is still in beta**, so we'd cross-check it with your actual revenue and fees. Incorrect RevenueCat [Small Business Program dates](https://www.revenuecat.com/docs/platform-resources/apple-platform-resources/app-store-small-business-program#informing-revenuecat) can skew its commission data. > > **Example:** \$10 gross ARPU, 60% web / 40% IAP revenue, assumed fees of 2% web / 30% IAP: > > * App2Web: `$10 x (0.60 x 0.98 + 0.40 x 0.70) = $8.68` (**24% more**). > * IAP-only: `$10 x 0.70 = $7.00`. > > Use your own fees here; these are illustrative rates. Weight by revenue share, not conversion share, unless revenue per conversion is equal. > > This example excludes taxes, refunds, and renewals. Revisit equal-age cohorts as revenue accumulates; stronger web renewals can increase lift. # App2Web Go-Live Checklist Source: https://docs.tryhelium.com/guides/app2web-go-live-checklist A short checklist for testing your App2Web flow before launch. A checklist for testing your App2Web flow before sending traffic to it. The testing tool itself — [Paywall Previews](/guides/paywall-previews) — lets you run the full app-to-web checkout, including simulated or real purchases, without meeting production targeting. ## Check the setup * [ ] The in-app App2Web paywall and hosted web paywall are linked and published. * [ ] The hosted web paywall is reached only through the in-app App2Web flow, not directly from a workflow. * [ ] Web products are attached correctly, and the normal IAP path remains available through `continue in-app`. * [ ] Targeting includes only eligible users and has been tested with an internal audience. * [ ] Checkout redirect URL, user identity, revenue tracking, and subscription management are configured. ## Test with Paywall Previews Open [Paywall Previews](/guides/paywall-previews#preview-paywalls-from-your-app) (triple tap) and select your App2Web paywall. * [ ] Check the [purchase mode](/guides/app2web-previews#simulated-and-real-purchases) in the [preview settings](/guides/app2web-previews#preview-settings) before each session — eligible devices default to real purchases, which charge your card. * [ ] Run a simulated purchase and confirm no transaction or entitlement is created. * [ ] If the device is [eligible](/guides/app2web-previews#purchase-eligibility), run a real purchase and confirm the entitlement is granted. * [ ] For Paddle paywalls, verify the California consent modal when it applies. * [ ] [Clean up test purchases](/guides/app2web-previews#how-preview-events-differ-from-production) in your Paddle dashboard when done. ## Test with a real trigger Previews [bypass targeting and skip paywall traits](/guides/app2web-previews#what-app2web-previews-dont-cover). Before launch, run the flow through a real trigger on a physical device: * [ ] Open App2Web through a real trigger. * [ ] Tapping the web purchase CTA opens the linked hosted web paywall in the browser. * [ ] The product selected in the app is the product selected on the hosted web paywall. * [ ] Product selection and the web purchase action are separate, so the CTA cannot send the wrong product. * [ ] `continue in-app` opens the intended IAP purchase path. * [ ] Dismissing or abandoning web checkout returns the user to the expected place without granting access. * [ ] Complete a web purchase and confirm the app reopens with an active entitlement. * [ ] Confirm the purchase appears in Helium and your connected revenue or entitlement system. ## Launch * [ ] Start with a small eligible audience and confirm the flow is healthy before expanding traffic. * [ ] Use your provider’s App2Web eligibility targeting preset and route users outside that audience to an IAP paywall. # App2Web Paywall Previews Source: https://docs.tryhelium.com/guides/app2web-previews Test the full app-to-web checkout flow — simulated or real purchases — before your paywall is live. > [!NOTE] > > iOS only. See the [minimum SDK versions](/guides/paywall-previews#app2web-previews). On Android, App2Web checkout APIs are safe no-ops. If a paywall uses App2Web, previewing it from [Paywall Previews](/guides/paywall-previews) exercises the full flow: the in-app paywall opens, the purchase action kicks out to the hosted web checkout, and you can complete a simulated or real purchase — all before the paywall is live and without meeting production targeting. ## Simulated and real purchases Previews support two purchase modes: * **Simulated purchase** — the checkout looks and behaves like the real flow, but no transaction is created, no revenue events fire, and no entitlement is granted. Useful for checking the experience without spending money, especially where real purchases aren't available. * **Real purchase** — charges your card, completes checkout, returns to your app, and grants a real entitlement. Useful for verifying webhooks and entitlement delivery. The mode follows the device's purchase eligibility: a device that is not cleared for real purchases always runs simulated, while an eligible device defaults to a real purchase. You can switch an eligible device to simulated in the preview settings. ## Purchase eligibility Real purchases follow the same regional rules as production. The device's locale, App Store country, and network location must agree: * **US, outside California** — real purchases available. * **US, California** — real purchases available, and the California consent modal is required before a Paddle checkout. * **Outside the US, or mixed signals** (for example a VPN with a non-US App Store account) — simulated purchases only. To test the real purchase path from outside the US, all three signals must read US: use a US App Store account, set the device region to the US, and connect through a VPN to a US state. ![California consent modal shown before activating a Paddle subscription](https://mintcdn.com/helium/TLVewIOgiGu9osCK/images/paywall-previews-ca-consent-modal.png?fit=max\&auto=format\&n=TLVewIOgiGu9osCK\&q=85\&s=5ea991db408a1205be8bdd1aac68bddd) ## Preview settings Tap the **gear icon** on the previews list to open the App2Web preview settings: ![The gear icon on the previews list](https://mintcdn.com/helium/TLVewIOgiGu9osCK/images/paywall-previews-gear-icon.png?fit=max\&auto=format\&n=TLVewIOgiGu9osCK\&q=85\&s=d69c9aea3263529409b158d8921b3397) ![App2Web preview settings](https://mintcdn.com/helium/TLVewIOgiGu9osCK/images/paywall-previews-a2w-settings.png?fit=max\&auto=format\&n=TLVewIOgiGu9osCK\&q=85\&s=38c869943cc3c860fe4b0074641a470b) * **Purchase mode** — simulated or real, subject to the device's eligibility. * **California consent modal** — shown only for paywalls with a Paddle checkout; on eligible California devices the modal is required and the toggle cannot be turned off. Settings apply to every App2Web preview for the current session and reset when the app restarts. ## How preview events differ from production Preview events are real Helium events, with test markers that keep them separable from production: * The trigger is always the dedicated preview trigger (`helium_preview_trigger`), so preview activity never mixes with your real triggers. * No experiment or allocation info is attached — previews bypass experiments. * Paywall traits are not applied, so trait-driven content renders with defaults. * A real purchase done through Paywall Previews carries `helium_testing: true` on the resulting Paddle subscription's `custom_data`. ## What App2Web previews don't cover Previews bypass audience targeting and do not exercise paywall traits. Before launch, also open the flow through a real trigger on a physical device — see the [go-live checklist](/guides/app2web-go-live-checklist). ## Web paywalls Web paywalls can't be previewed directly — they only back an App2Web paywall. Selecting one in the previews list explains this and names the linked in-app paywall when there is one. Run the App2Web preview on that in-app paywall to see the full checkout flow. ## Troubleshooting * If a paywall was last saved before App2Web preview support, the preview is blocked with a message asking you to re-save it in the dashboard. # Build an App2Web Paywall Source: https://docs.tryhelium.com/guides/build-app2web-paywall Add web checkout to an existing in-app purchase paywall. App2Web links an in-app paywall to a browser checkout. Start with a working IAP paywall and your web products synced to Helium. To open the web paywall, add a **purchase action for a web product to the in-app paywall**. Helium opens its linked web paywall, where the user completes the purchase. You don’t need to open a checkout URL yourself. ## Adapt the in-app paywall 1. Duplicate your paywall. Offer web checkout and **Continue in-app** in a multi-step flow. 2. Add web products. Use iOS-only buckets for the IAP path; duplicate mixed-platform buckets if needed. 3. Set the web CTA to **purchase the web product**, not just select it or open a URL. Keep product selection separate from purchase. 4. Route **Continue in-app** to IAP. After opening web checkout, also move the in-app screen to IAP for users returning without purchasing. ## Link the hosted web paywall 1. Create and link the hosted paywall. Use your web provider's products, with matching initial selections on both screens. 2. Match your IAP layout, leaving space for browser controls and disclosures. Use **Back** to dismiss; keep restore actions in-app. 3. Publish both paywalls. Target the **in-app** paywall to eligible users; hosted paywalls cannot be targeted or added to experiments directly. Dismissing the hosted web paywall or completing a subscription returns the user to your app. > [accordion] Design tips > > * Keep the primary CTA in the same position across screens. > * Keep custom logic in-app; hosted paywalls have limited variable, payload, and localization support. > * Check [names and pricing](/guides/app2web-faq#checkout-appearance) in the payment sheet. Next: [Go-live checklist](/guides/app2web-go-live-checklist) / [Evaluate your experiment](/guides/app2web-faq#experiment-results). # Handling Custom Paywall Events Source: https://docs.tryhelium.com/guides/custom-events Send custom events from your paywall to your app to trigger actions beyond purchases. ## Overview Helium's event handling system has native handlers for most common paywall events (purchases, navigation, etc), but in some cases you might want to have custom interactions on your paywall that aren't handled by default. For example, you might want to have a toggle that when selected sends a trial notification reminder using your own notification system. Helium lets you do this with **Custom Events**. ## Custom Events A custom event is fired from the paywall and handled from the SDK. You can have as many different types of custom events as you want within a single paywall. Custom events have a few properties: **Action Name** - (String) The name of the event. For example, "did_switch_trial_toggle" **Params** - (Dictionary of string keys -> any type of value) Dictionary of arbitrary parameters associated with the action. The keys have to be strings, the values can be numbers, boolean, strings, arrays, or dictionaries themselves. For example, ``` { "is_toggle_selected": False, "iso_timestamp": 13041241255 } ``` We recommend asking the editor to separate out different interactions into different actions. For example, if you have * a trial notification toggle * a little survey that you ask the user within the paywall * a custom dismiss button Separating these out into different actions with their own parameters will make it easier to handle from the SDK side. There are two steps to setting up custom event handling with Helium: ## Editor: Add a button that emits a custom action to your paywall In the Helium paywall editor, you can add a button or interaction that sends a custom action by just asking the chat. For example, * Add a trial reminder toggle using custom actions. * Add a button that triggers requesting permissions for location if a user press an opt in button. * Make it so that if the user selects the Watch Ads button, the editor sends a custom action to handle so that the SDK can handle that case on purchase pressed " Some tips: * You can verify the editor is using a custom action using the **Actions Panel**. * Feel free to tell the editor the specific action name and params you want it to use! * Reach out to support with your use case - happy to set this up for you and tell you what the corresponding SDK code should look like to handle the new event! ## SDK: Add an onCustomPaywallAction handler Then, within your SDK you can use Paywall Event Handlers with the `onCustomPaywallAction` event. Visit our SDK's quickstart pages for more info on getting set up with the SDK. > [tab] iOS > > ```swift theme={null} > Helium.shared.presentPaywall( > trigger: "your_trigger", > eventHandlers: PaywallEventHandlers() > .onCustomPaywallAction { event in > if event.actionName == "your_action_name", > let value = event.params["key1"] as? String { > // Handle your custom action > // E.g., mark that we should send a notification on purchase > print("Received: \(value)") > } > } > ) > ``` > > The `CustomPaywallActionEvent` contains: > > * `actionName`: The action name > * `params`: Dictionary of parameters > * `triggerName`: The trigger that opened this paywall > * `paywallName`: The name of the paywall > * `timestamp`: ISO timestamp for when the event occurred > [tab] Android > > ```kotlin theme={null} > import com.tryhelium.paywall.core.event.PaywallEventHandlers > import kotlinx.serialization.json.jsonPrimitive > import kotlinx.serialization.json.contentOrNull > > Helium.shared.addPaywallEventListener( > lifecycleOwner = this, // Your activity or fragment > listener = PaywallEventHandlers( > onCustomPaywallAction = { event -> > if (event.actionName == "your_action_name") { > // Extract a string value from the params > val value = event.params["key1"]?.jsonPrimitive?.contentOrNull > > // Handle your custom action > Log.d("PaywallEvents", "Received custom action with value: $value") > } > } > ) > ) > ``` > > The `CustomPaywallAction` event contains: > > * `actionName`: The name of the event. > * `params`: A `JsonObject` of arbitrary parameters associated with the action. > * `triggerName`: The trigger that opened this paywall. > * `paywallName`: The name of the paywall. > * `timestamp`: Unix timestamp for when the event occurred. > [tab] React Native > > ```typescript theme={null} > import { presentUpsell } from 'expo-helium'; > // or: import { presentUpsell } from '@tryheliumai/paywall-sdk-react-native'; > > presentUpsell({ > triggerName: 'your_trigger', > eventHandlers: { > onCustomPaywallAction: (event) => { > if (event.actionName === 'your_action_name') { > const value = event.params.key1; > // Handle your custom action > console.log('Received:', value); > } > }, > }, > }); > ``` > > The `CustomPaywallActionEvent` contains: > > * `actionName`: The action identifier from JavaScript > * `params`: Object of parameters from JavaScript > * `triggerName`: The trigger that opened this paywall > * `paywallName`: The paywall template name # Dashboard FAQ Source: https://docs.tryhelium.com/guides/dashboard-faq Short answers to common questions about paywalls, workflows, triggers, targeting and experiments in the Helium dashboard. Answers use the names you see in the dashboard. For the concepts behind them, start with [How Helium Works](/guides/how-does-helium-work). ## Paywalls > [accordion] How do I take a paywall live? > > A paywall shows to users once it is published and a workflow with a trigger points at it, and your app calls the Helium SDK with that trigger. Allow a few minutes after publishing for devices to start receiving it. > > **1. Link products** > > Open the Products panel in the editor and choose the Product Buckets the paywall should sell. Buckets are managed on the **Products** tab of the Integrations page. > > **2. Publish it** > > In the paywall editor click **Publish Draft**, or **Save and Publish** if you have unsaved changes. > > **3. Create a workflow** > > On the Workflows page click **New Workflow**, give it a title and choose the **Control paywall**. Only published paywalls can be chosen. An unselectable paywall is greyed out; hover over it to see the reason. > > **4. Decide who sees it** > > On the workflow page, **Everyone else sees** is the paywall shown when no rule matches. Click **Add rule** to show a different paywall, run an experiment, or show no paywall to a specific audience. > > **5. Attach a trigger** > > In the Triggers card click **Add trigger**, then pick an existing unused trigger or **Create New Trigger** using letters, numbers and underscores. This trigger is the string your app passes to the Helium SDK. **Copy trigger** copies it. A workflow with no trigger never serves. > > **6. Check the Live badge** > > On the Paywalls page the paywall shows **Live** once it is a workflow's control paywall, is named in a "show paywall" rule, or is a variant in a running experiment. Otherwise it shows **Inactive**. > > **7. Download fallbacks** > > On the Workflows page open the **...** menu and click **Download Fallbacks**, set the iOS and Android defaults and add the file to your app. The file is a snapshot of the versions published at download time, so when you make a meaningful change to a paywall consider downloading it again with your next app release. See [Fallback Paywalls](/guides/fallback-bundle). > > > [!NOTE] > > > > Published but not Live? No workflow points at the paywall yet, it is only in an experiment that is not running, or the rule that named it was archived. The Live badge checks workflow and experiment wiring only, so also confirm the workflow has a trigger. > [accordion] How do I turn off a paywall? > > There is no Unpublish or Archive button on a paywall. A paywall shows wherever a workflow or running experiment points at it, so you turn it off by changing that. > > 1. **Stop it serving.** Open the workflow that uses it. Change **Everyone else sees** to a different paywall, or open the rule that names it and edit it, **Archive** it, or switch it to **show no paywall**. If the paywall is an experiment variant, use **Remove from experiment** on the variant. Once nothing points at it, the Paywalls page shows it as **Inactive**. This takes effect right away and can be undone. > 2. **Fix the content instead.** In the editor open the **...** menu, choose **Version History**, click **View** on a known-good version, then **Save** and **Publish**. Publishing the older content as a new version replaces what devices get. > 3. **Delete** removes the paywall for good and cannot be undone. Move workflows off it first. ## Workflows and triggers > [accordion] How do I move a trigger to a different workflow? > > A trigger belongs to one workflow at a time. > > 1. Open the workflow that has the trigger today. > 2. In the Triggers card click the trigger, then **Move to Different Workflow**. > 3. Pick the destination under **Select Workflow** and click **Move Trigger**. > > Your app code does not change. The trigger stays the same and starts serving the new workflow's paywalls right away. The old workflow keeps running for any other triggers it has. With none left it shows "No triggers" and serves nothing. > > Also good to know: > > * A trigger cannot be on two workflows at once, and the **Add trigger** picker only lists triggers that are not in use. > * A trigger cannot be renamed, only its description (**Edit**). > * **Delete** is only offered for triggers under Unassigned Triggers on the Workflows page. Remove or move a trigger out of its workflow first. ## Experiments > [accordion] Can I pause an experiment? > > No. An experiment is either running or stopped, and **Stop experiment** is final: a stopped experiment cannot be started again. When you stop one, the **Stop Experiment** dialog asks where traffic should go next, one of the variants' paywalls or **Next Matching Audience**, and applies that to the workflow when you click **Stop Experiment & Route Traffic**. > > To take an experiment out of rotation without ending it, change the workflow instead: edit or **Archive** the rule that runs it, or change **Everyone else sees**. The experiment then shows **Not Live** while its status stays running, and you can point a rule back at it later. > [accordion] Can I duplicate an experiment? > > No. **Copy Experiment ID** only copies the id. To rerun a test, create a **New Experiment** on the workflow, add the same paywalls as variants, and enter the same traffic allocation. Each variant takes 1 to 100 percent. ## Metrics > [accordion] What percent of conversions came from the second try flow? > > Helium does not report second try conversions as their own metric or filter yet. Paywall Views and Conversions on the Metrics page count the second try paywall together with the paywall it belongs to. # Fallback Paywalls Source: https://docs.tryhelium.com/guides/fallback-bundle How to download fallback paywalls from the dashboard and include it in your app. ## What are "fallbacks"? The Helium SDK does its best to fetch the latest paywalls to display in your app. But if for some reason a paywall is not available — perhaps if an app user temporarily did not have a data connection — Helium will attempt to show a "fallback". You can download copies of your actual Helium paywalls and include that in your app to use in the rare case that a Helium paywall is not ready for display. ## Download Fallbacks Go to the [Workflows](https://app.tryhelium.com/workflows) page in your dashboard and find the **Download Fallbacks** button: ![Download Fallbacks 1 Pn](https://mintcdn.com/helium/vjbIVTFp_dv4L6zW/images/download_fallbacks_1.png?fit=max\&auto=format\&n=vjbIVTFp_dv4L6zW\&q=85\&s=9c7c760c7386d74e0ac283f144312a53) This will open a dialog and allow you to select which paywall/s to use as fallback. Most of the time you only need to set Default Fallbacks. After selection, click **Download** and your browser should download a file named **helium-fallbacks.json**. > [!TIP] > > Whenever you update paywalls consider whether you want to repeat this process to update your fallbacks. ## Add fallbacks to your Helium SDK integration > [tab] iOS > > 1. Integrate the SDK with the [iOS Quickstart](/sdk/quickstart-ios) if you haven't done so already. > > 2. Drag your downloaded file into the Project navigator of your Xcode project. > > 3. You should see a dialog with **Action** and **Targets** fields. For **Action**, select your preference between the move and copy options. For **Targets** ensure that your app's main target is selected. > > 4. That's it! The SDK automatically detects any file with the name `helium-fallbacks.json`. > > > [!TIP] > > > > To use a custom file name, set it before calling `initialize()`: > > > > ```swift theme={null} > > Helium.config.customFallbacksURL = Bundle.main.url( > > forResource: "fallback-bundle-xxxx-xx-xx", > > withExtension: "json" > > ) > > ``` > [tab] Android > > 1. Integrate the SDK with the [Android Quickstart](/sdk/quickstart-android) if you haven't done so already. > > 2. In your app's `src/main` directory, create an `assets` folder if one doesn't already exist. > > 3. Drag your downloaded bundle into the `assets` folder. > > 4. That's it! The SDK automatically detects `helium-fallbacks.json` in your assets. > > > [!TIP] > > > > To use a custom file name, set it before calling `initialize()`: > > > > ```kotlin theme={null} > > Helium.config.customFallbacksFileName = "fallback-bundle-xxxx-xx-xx.json" > > ``` > [tab] React Native > > 1. Integrate the SDK with the [React Native Quickstart](/sdk/quickstart-react-native) if you haven't done so already. > 2. Drag your downloaded bundle into your React Native project where desired. > 3. Pass in to `Helium.initialize` > > ```typescript theme={null} > const fallbackBundle = require('./assets/fallback-bundle-xxxx-xx-xx.json'); > > initialize({ > apiKey: apiKey, > // ... other parameters ... > fallbackBundle: fallbackBundle, > }); > ``` > > > [!NOTE] > > > > Make sure to use the correct path and filename in your `require` call! > [tab] Flutter > > 1. Integrate the SDK with the [Flutter Quickstart](/sdk/quickstart-flutter) if you haven't done so already. > 2. Drag your downloaded bundle into your Flutter project where desired. > 3. In your `pubspec.yaml` add the new asset: > > ```yaml theme={null} > assets: > - .env > - fallback-bundle-xxxx-xx-xx.json # add this line > ``` > > 4. Pass in to `Helium.initialize` > > ```dart theme={null} > heliumFlutter.initialize( > // ... other parameters ... > fallbackBundleAssetPath: "fallback-bundle-xxxx-xx-xx.json" > ``` > > > [!NOTE] > > > > Make sure to use the correct filename in both `pubspec.yaml` and the call to `initialize`! ## Testing Fallbacks Look at your debug log output when running a debug build of your app to see if fallbacks are successfully loaded. To see a fallback paywall, you can run your app in airplane mode or use a non-existent trigger when presenting a paywall. ## How to Monitor and Minimize Fallback Rate You can check your app's fallback rate by going to your [Metrics page](https://app.tryhelium.com/metrics) and clicking on the "Fallback Rate" tab under Monitoring. This rate shows the percentage of paywall opens that use a fallback paywall. If you notice your fallback rate is higher than expected, here are some tips on minimizing it: * **Move your initialize() call earlier in your app's lifecycle.** We recommend doing so right when your app is launched. * **Set a higher loading budget.** If your paywall is still downloading when presented, Helium will show a loading state. The default loading budget of 7 seconds is generally plenty of time to ensure your paywall will show before fallback is used. But if you have overridden the budget to be a lower value, consider increasing it. * **Reduce the size of image assets in your paywall.** We recommend keeping each paywall to be under about 3-5 MB in total size. If you're adding high resolution imagery to your paywall (which is fine!) we recommend converting images to .webp format - e.g. with an online converter like [https://cloudconvert.com/webp-converter](https://cloudconvert.com/webp-converter). If you still see a rate higher than expected, please get in touch! ## Fallback Causes ### Paywall is still downloading > [!NOTE] > > This is the most common reason. Helium fetches your latest paywalls when the Helium SDK is initialized. If a user is on a very slow connection or has no connection at all, a fallback will be shown. ### Paywalls failed to download Similarly, if user has no connection or a very limited connection, the paywall retrieval may fail entirely. Or in the unlikely event Helium servers are temporarily down. ### No products associated with paywall for platform Can occur when a paywall is downloaded but does not have products properly linked for the platform (iOS/Android) it is served to. ### Other Causes The above are the most likely causes, but a fallback can also occur if paywall html is malformed or from any other unexpected Helium bug. # Google Play Data Safety (Android) Source: https://docs.tryhelium.com/guides/google-play-data-safety What to declare in your Play Console Data safety section when your app includes the Helium Android SDK. Google Play requires every developer to declare how their app collects and handles user data, **including data handled by any third-party SDK they bundle**. This page tells you which boxes to tick in the Play Console **Data safety** section when your app includes the Helium Android SDK. > [!NOTE] > > Google is explicit that the declaration is yours to make: "You alone are responsible for making complete and accurate declarations in your app's store listing on Google Play." This page covers the Helium SDK only. Your final declaration must also account for your own app's data collection and every other SDK you ship. ## Data collection and security Three questions gate the rest of the form. ### Does your app collect or share any of the required user data types? Select **Yes**. Helium collects a device identifier, purchase history, and paywall interaction data. ### Is all of the user data collected by your app encrypted in transit? Select **Yes** as far as Helium is concerned. All Helium network traffic uses HTTPS. > [!WARNING] > > Google only lets you select "Yes" if encryption in transit applies to **all** user data your app and every one of its SDKs transmits off the device. Confirm this holds across your whole app before selecting it. ### Do you provide a way for users to request that their data is deleted? This one depends on your own support process, not on Helium. If you select **Yes**, make sure users have a route to reach you, such as an in-app link, a contact form, or a support email. On the client, `Helium.resetHelium()` clears the locally persisted Helium identity and user traits. For deletion of data already sent to Helium, contact Helium support. ## Data types > [!NOTE] > > ✅ Required when using Helium > > 💡 May be required, depending on how you configure the SDK > > ❌ Not collected by Helium | Category | Data type | Required? | | - | - | - | | Location | Approximate location, Precise location | ❌ Helium reads no location APIs and declares no location permission. It collects device locale, currency, and Play store country, which Google does not classify as location. | | Personal info | User IDs | 💡 Only if you set `Helium.identity.userId`, `revenueCatAppUserId`, or `thirdPartyAnalyticsAnonymousId` to a value that relates to an identifiable person, such as your own account ID. If you set none of them, Helium falls back to its generated installation ID, which is covered by Device or other IDs below. | | Personal info | Name, Email address, Phone number, Address | 💡 Only if you put them into `HeliumUserTraits`, or if you use the optional Stripe module. | | Financial info | **Purchase history** | ✅ Helium collects product IDs, Google Play order IDs and purchase tokens, purchase dates, quantity, and store country. | | Financial info | User payment info | 💡 Optional Stripe module only. | | Financial info | Credit score, Other financial info | ❌ | | Health and fitness | All types | ❌ | | Messages | All types | ❌ | | Photos and videos | All types | ❌ | | Audio files | All types | ❌ | | Files and docs | Files and docs | ❌ | | Calendar | Calendar events | ❌ | | Contacts | Contacts | ❌ | | App activity | **App interactions** | ✅ Paywall opens, closes and dismissals, button presses, product selection, purchase flow steps, and experiment allocation. | | App activity | Other actions | 💡 Only if your paywalls emit custom actions carrying additional user activity. | | App activity | In-app search history, Installed apps, Other user-generated content | ❌ | | Web browsing | Web browsing history | ❌ Paywalls render inside a WebView that loads Helium-controlled content. Helium does not read browsing history. | | App info and performance | **Diagnostics** | ✅ Paywall load and render timings, configuration download outcomes, retry counts, and error descriptions. | | App info and performance | Crash logs, Other app performance data | ❌ Helium bundles no crash reporter. | | Device or other IDs | **Device or other IDs** | ✅ The Android ID (`Settings.Secure.ANDROID_ID`), plus Helium's own generated installation, session, and initialization IDs. | > [!TIP] > > Helium declares more than a billing-only SDK would, because paywall interaction data is what powers experiments and optimization rather than being a side effect. The four bolded rows above are the ones you always need. ## Answering the per-data-type questions For each data type you select, Google asks four follow-up questions. All four required Helium data types (Purchase history, App interactions, Diagnostics, and Device or other IDs) get the same answers. Any 💡 rows that apply to your setup generally follow the same pattern, though review the purposes for your own case. ### Is this data collected, shared, or both? Select **Collected** if Helium processes this data solely on your behalf and under your instructions. That is Google's test for a service provider, and sharing does not apply. Select **Collected** and **Shared**, and declare the purposes of that sharing, if either of the following is true: * Helium uses your app's data for its own cross-customer optimization or experiment purposes rather than solely on your instructions. * You forward Helium events to third parties that are not acting as your service providers. > [!WARNING] > > Google is explicit that "if an SDK provider is building advertising profiles across multiple customers based on your app data, that would not be considered 'service provider' activity." Confirm which of the above describes your contract and configuration before answering. ### Is this data processed ephemerally? Select **No**. Helium retains this data to power paywall experimentation and reporting. ### Is this data required for your app, or can users choose whether it's collected? Select **Data collection is required** by default. The Helium SDK does not expose a per-user opt-out, so once you initialize it, collection begins. > [!TIP] > > You can declare this data **optional** instead if you gate `Helium.initialize()` behind your own consent prompt and only call it for users who agree. Google's bar is that all users, regardless of device or region, must be able to opt in or out. > [!NOTE] > > A consent gate answers this Play Data safety question only. It does not by itself establish compliance with GDPR, CCPA, or other privacy regimes, which impose separate requirements such as having a lawful basis for processing, giving notice at collection, and handling consumer rights requests. Review the jurisdictions you operate in with privacy counsel. ### Why is this user data collected? Select **App functionality** and **Analytics**. > [!NOTE] > > Also select **Personalization** if you use audience targeting or experiment rules that tailor which paywall a user sees based on traits you provide. ## What Helium does not collect Worth knowing, because it keeps several categories off your form entirely: * **No advertising identifier.** Helium does not read the Google Advertising ID or App Set ID, and declares no `com.google.android.gms.permission.AD_ID` permission. * **No location.** No location APIs, no location permissions. * **No contacts, photos, videos, audio, files, calendar, or messages.** * **No crash logs.** Helium bundles no crash reporting library. * **No health or fitness data.** The SDK contributes only these permissions to your merged manifest: | Permission | Why | | - | - | | `android.permission.INTERNET` | Fetching paywall configuration and bundles | | `android.permission.ACCESS_NETWORK_STATE` | Detecting connectivity before network calls | | `com.android.vending.BILLING` | Google Play Billing, for purchases and entitlements | ## Optional modules Two Helium modules change your answers if you use them. > [tab] RevenueCat > > The `revenue-cat` module sets Helium's persistent installation ID as the RevenueCat app user ID, and by default also as a `helium_hpid` subscriber attribute. You can turn the attribute off by constructing the delegate with `allowHeliumUserAttribute = false`. > > Using this module means RevenueCat's own data collection applies to your app as well. Refer to [RevenueCat's Data Safety guidance](https://www.revenuecat.com/docs/platform-resources/google-platform-resources/google-plays-data-safety) alongside this page. ## What's next > [card] [Identifying Users](/sdk/quickstart-android) > > How `Helium.identity.userId` and `HeliumUserTraits` work, which drive the conditional rows above > [card] [Google's Official Guidance](https://support.google.com/googleplay/android-developer/answer/10787469) > > Play Console documentation for the Data safety section # Helium Events Source: https://docs.tryhelium.com/guides/helium-events Reference for every event the Helium SDK emits (initialization, paywall open and close, purchases, failures) with the fields on each. ## Overview Helium emits paywall and lifecycle events related to paywalls, purchasing, configuration, and experimentation. This page acts as a reference to what events are available in Helium, and when each one is fired. Visit each SDK's quickstart page to see how to listen for and handle events. ## Event Types > [tab] iOS > > ```swift theme={null} > // Base protocol for all events > protocol HeliumEvent { > var eventName: String { get } > var timestamp: Date { get } > func toDictionary() -> [String: Any] > } > > // Events with paywall context > protocol PaywallContextEvent: HeliumEvent { > var triggerName: String { get } > var paywallName: String { get } > var isSecondTry: Bool { get } > } > > // Product-related events > protocol ProductEvent: PaywallContextEvent { > var productId: String { get } > } > > // All Event Types: > // Lifecycle: PaywallOpenEvent, PaywallCloseEvent, PaywallDismissedEvent, > // PaywallSkippedEvent, PaywallButtonPressedEvent > // Purchase: ProductSelectedEvent, PurchasePressedEvent, PurchaseSucceededEvent, > // PurchaseCancelledEvent, PurchaseFailedEvent, PurchaseRestoredEvent, > // PurchaseRestoreFailedEvent, PurchasePendingEvent, > // PurchaseAlreadyEntitledEvent > // System: InitializeStartEvent, PaywallsDownloadSuccessEvent, > // PaywallsDownloadErrorEvent, PaywallWebViewRenderedEvent > // Experiment: UserAllocatedEvent > ``` > [tab] Android > > ```kotlin theme={null} > // Base sealed class for all events > sealed class HeliumEvent( > open val timestamp: Long > ) > > // Events with paywall context > sealed class PaywallContextEvent( > override val timestamp: Long, > open val triggerName: String, > open val paywallName: String, > open val isSecondTry: Boolean, > ) : HeliumEvent(timestamp) > > // Product-related events > sealed class ProductEvent( > override val timestamp: Long, > override val triggerName: String, > override val paywallName: String, > override val isSecondTry: Boolean, > open val productId: String, > ) : PaywallContextEvent(timestamp, triggerName, paywallName, isSecondTry) > > // All Event Classes: > // Lifecycle: PaywallOpen, PaywallClose, PaywallDismissed, PaywallOpenFailed, > // PaywallSkipped, PaywallButtonPressed > // Purchase: ProductSelected, PurchasedPressed, PurchaseSucceeded, PurchaseCancelled, > // PurchaseFailed, PurchaseRestored, PurchaseRestoreFailed, PurchasePending > // System: InitializeStart, InitializeCalled, PaywallsDownloadSuccess, > // PaywallsDownloadError, PaywallWebViewRendered > ``` > [tab] React Native > > ```typescript theme={null} > export type HeliumPaywallEvent = { > type: 'paywallOpen' | 'paywallClose' | 'paywallDismissed' | > 'paywallOpenFailed' | 'paywallSkipped' | 'paywallButtonPressed' | > 'productSelected' | 'purchasePressed' | 'purchaseSucceeded' | > 'purchaseCancelled' | 'purchaseFailed' | 'purchaseRestored' | > 'purchaseAlreadyEntitled' | > 'purchaseRestoreFailed' | 'purchasePending' | 'initializeCalled' | > 'paywallsDownloadSuccess' | 'paywallsDownloadError' | > 'paywallWebViewRendered' | 'userAllocated'; > triggerName?: string; > paywallName?: string; > productId?: string; > buttonName?: string; > configId?: string; > numAttempts?: number; > downloadTimeTakenMS?: number; > webviewRenderTimeTakenMS?: number; > imagesDownloadTimeTakenMS?: number; > fontsDownloadTimeTakenMS?: number; > bundleDownloadTimeMS?: number; > dismissAll?: boolean; > isSecondTry?: boolean; > error?: string; > experimentInfo?: ExperimentInfo; > timestamp?: number; > } > ``` > [tab] Flutter > > ```dart theme={null} > // Base event structure > abstract class HeliumEvent { > String get eventName; > DateTime get timestamp; > Map toMap(); > } > > // Events with paywall context > abstract class PaywallContextEvent extends HeliumEvent { > String get triggerName; > String get paywallName; > bool get isSecondTry; > } > > // Product-related events > abstract class ProductEvent extends PaywallContextEvent { > String get productId; > } > > // All Event Types: > // Lifecycle: PaywallOpenEvent, PaywallCloseEvent, PaywallDismissedEvent, > // PaywallOpenFailedEvent, PaywallSkippedEvent, PaywallButtonPressedEvent > // Purchase: ProductSelectedEvent, PurchasePressedEvent, PurchaseSucceededEvent, > // PurchaseCancelledEvent, PurchaseFailedEvent, PurchaseRestoredEvent, > // PurchaseRestoreFailedEvent, PurchasePendingEvent > // System: InitializeStartEvent, PaywallsDownloadSuccessEvent, > // PaywallsDownloadErrorEvent, PaywallWebViewRenderedEvent > ``` ## Available Events ### Paywall and Purchase Events | Event Name | Description | Parameters | | - | - | - | | **paywallOpen** | Fires when a paywall is displayed | `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `viewType` (String) - presented, triggered, or embedded `loadTimeTakenMS` (Number, optional) - Loading time in milliseconds `loadingBudgetMS` (Number, optional) - Loading budget in milliseconds `timestamp` (Number) - When event occurred | | **paywallClose** | Fires when a paywall is closed (removed from view hierarchy). **Fires on both explicit dismissal AND purchase success** | `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **paywallDismissed** | Fires when paywall is explicitly dismissed by user | `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `dismissAll` (Boolean) - Whether entire paywall stack dismissed `timestamp` (Number) - When event occurred | | **paywallSkipped** | Fires if paywall display is skipped due to targeting, workflow configuration, or existing entitlement | `triggerName` (String) - Associated trigger `timestamp` (Number) - When event occurred | | **paywallButtonPressed** | Fires when a non-purchase button is pressed | `buttonName` (String) - Button identifier `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **paywallWebViewRendered** | Fires when the paywall content has finished rendering | `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `webviewRenderTimeTakenMS` (Number, optional) - Time to render in milliseconds `timestamp` (Number) - When event occurred | | **productSelected** | Fires when a user selects a product on the paywall | `productId` (String) - Product identifier `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **purchasePressed** | Fires when a purchase button is pressed in the paywall | `productId` (String) - Product being purchased `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **purchaseSucceeded** | Fires when a purchase is successfully completed. | `productId` (String) - Product identifier `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `storeKitTransactionId` (String, optional) - Transaction ID `storeKitOriginalTransactionId` (String, optional) - Original transaction ID `skPostPurchaseTxnTimeMS` (Number, optional) - Post-purchase transaction time `timestamp` (Number) - When event occurred | | **purchaseCancelled** | Fires when the purchase process is cancelled by the user | `productId` (String) - Product that was cancelled `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **purchaseFailed** | Fires when the purchase fails for any reason | `productId` (String) - Product that failed `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `error` (String, optional) - Error message `timestamp` (Number) - When event occurred | | **purchaseRestored** | Fires when a previous purchase is successfully restored | `productId` (String) - Restored product ID `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **purchaseAlreadyEntitled** | Fires when a purchase attempt resolves to an entitlement the user already had (iOS only). Not a new revenue event | `productId` (String) - Product the user already owns `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `storeKitTransactionId` (String, optional) - Existing transaction ID `storeKitOriginalTransactionId` (String, optional) - Original transaction ID `timestamp` (Number) - When event occurred | | **purchaseRestoreFailed** | Fires when an attempt to restore purchases fails | `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | | **purchasePending** | Fires when purchase is in a pending state (e.g. waiting for parental approval) | `productId` (String) - Pending product `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `timestamp` (Number) - When event occurred | ### System Events | Event Name | Description | Parameters | | - | - | - | | **initializeCalled** | Fires when SDK initialization is called | `timestamp` (Number) - When event occurred | | **paywallsDownloadSuccess** | Fires when Helium paywalls downloaded and initialized successfully | `downloadTimeTakenMS` (Number, optional) - Config download time in milliseconds `imagesDownloadTimeTakenMS` (Number, optional) - Images download time in milliseconds `fontsDownloadTimeTakenMS` (Number, optional) - Fonts download time in milliseconds `bundleDownloadTimeMS` (Number, optional) - Bundle download time in milliseconds `numAttempts` (Number, optional) - Number of attempts made `timestamp` (Number) - When event occurred | | **paywallsDownloadError** | Fires when paywalls download failed | `error` (String) - Error description `numAttempts` (Number, optional) - Number of attempts made `timestamp` (Number) - When event occurred | | **paywallOpenFailed** | Fires if a paywall fails to open and fallback fails to show | `triggerName` (String) - Associated trigger `paywallName` (String) - Paywall name `isSecondTry` (Boolean) - True if paywall is "second try" flow `error` (String) - Error message describing failure `timestamp` (Number) - When event occurred | ### Experiment Events | Event Name | Description | Parameters | | - | - | - | | **userAllocated** | Fires once per user upon the first experimental paywall open. | `type` (String) - "userAllocated" `experimentInfo` (Object) - Complete experiment allocation data (see below) `timestamp` (Number) - When allocation occurred | ### Accessing ExperimentInfo from Events > [tab] iOS > > All paywall events (any event that implements `PaywallContextEvent`) provide a `getExperimentInfo()` method to access experiment allocation data on-demand: > > ```swift theme={null} > func onPaywallEvent(_ event: HeliumEvent) { > // Access experiment info from any paywall event > if let openEvent = event as? PaywallOpenEvent, > let experimentInfo = openEvent.getEventExperimentInfo() { > print("Variant: \(experimentInfo.chosenVariantDetails?.allocationIndex ?? 0)") > print("Experiment: \(experimentInfo.experimentName ?? "none")") > } > > // Track which variant led to purchase > if let purchaseEvent = event as? PurchaseSucceededEvent, > let experimentInfo = purchaseEvent.getEventExperimentInfo() { > analytics.track("conversion", variant: experimentInfo.chosenVariantDetails?.allocationIndex) > } > } > ``` > > You can also access experiment info directly by trigger: > > ```swift theme={null} > if let experimentInfo = Helium.shared.getExperimentInfoForTrigger("onboarding") { > print("Variant: \(experimentInfo.chosenVariantDetails?.allocationIndex ?? 0)") > } > ``` ### Fetch experiments for this user You can also fetch all experiments for the current user with a few methods available on the `Helium` top level object. Make sure to call these methods after `Helium.shared.initialize()` ```swift theme={null} // Gets all experiments for which this user is eligible func allExperiments() -> [ExperimentInfo]? // Gets all experiments for which this user is eligible AND has already been enrolled func enrolledExperiments() -> [ExperimentInfo]? ``` ### ExperimentInfo Structure The `experimentInfo` object in the `userAllocated` event contains experiment allocation data. This event fires once per session when a user is assigned to an experiment variant, which happens on the **first** trigger the user sees. #### Core Fields | Field | Type | Description | | - | - | - | | `enrolledTrigger` | String | The trigger where this user was enrolled in the experiment. | #### Experiment Details | Field | Type | Description | | - | - | - | | `experimentName` | String | Name of the experiment | | `experimentId` | String | Unique identifier for the experiment. You can look this experiment id up in the Helium dashboard | | `experimentType` | String | Type of experiment ("A/B/n test") | | `startDate` | String | When the experiment started (ISO8601 string) | | `endDate` | String | When the experiment is scheduled to end (ISO8601 string) | #### Targeting Details | Field | Type | Description | | - | - | - | | `audienceId` | String | Audience ID that user matched (for lookup in Helium) | | `audienceData` | String | Stringified JSON of the logged targeting logic. Useful for reference, though we recommend using the audience defined in the Helium dashboard. | #### Variant Details | Field | Type | Description | | - | - | - | | `chosenVariantDetails` | Object | Details about the assigned variant | | `chosenVariantDetails.allocationName` | String | Variant name. This will be the paywall name for paywall A/B/n tests. More names to come soon! | | `chosenVariantDetails.allocationId` | String | Variant UUID | | `chosenVariantDetails.allocationIndex` | Integer | Variant number (0-indexed) | #### Hash Details These fields provide information about how the user was deterministically assigned to a variant. | Field | Type | Description | | - | - | - | | `hashDetails` | Object | Hash bucketing information | | `hashDetails.hashedUserIdBucket1To100` | Integer | User's hash bucket (1-100) - deterministic value for consistent variant assignment | | `hashDetails.hashedUserId` | String | The actual user ID that was hashed (either the userId or heliumPersistentId depending on hashMethod) | | `hashDetails.hashMethod` | String | Hash method used: - `"HASH_USER_ID"`: we're hashing the user id passed into Helium.initialize() - `"HASH_HELIUM_PERSISTENT_ID"`: We're hashing a persistent device ID (does NOT persist across re-installs) | ## Logged Events All Helium events (see the full list [above](#available-events)) get logged to your analytics backend automatically with automatic event forwarding, along with the parameters listed there. Each event's parameters will usually show up as event properties. > [!NOTE] > > Event names and properties might show up as underscored/camelcase/JSON, depending on the platform. In addition, all lifecycle, paywall, downloadSuccess, and experimental events will include **contextual** and **custom** traits as event parameters: ### Contextual Traits Helium automatically and securely collects device and software attributes: * **Locale**: country, currency, currency symbol, language, preferred languages, time zone, decimal separator, uses metric system * **Screen**: brightness, bounds, native bounds, scale, native scale, dark mode enabled * **Device**: device identifier, orientation, system name, system version, device model, interface idiom, storage capacity * **Application**: version, build number, app name, Helium SDK version, environment ### Custom Traits Custom user traits included in the `Helium.initialize()` call also get sent as part of all events. If you pass custom user traits as part of a paywall presentation method call, these will **override** any custom traits of the same name passed in during `initialize()`. # Helium QA Guide Source: https://docs.tryhelium.com/guides/helium-qa-guide A short checklist for testing your Helium paywalls before launch. Use this checklist after your paywalls are built and before starting your rollout. > [!NOTE] > > Complete QA for the normal in-app purchase path first. If you also use App2Web, approve the IAP path before testing the full App2Web flow. ## Check the dashboard * [ ] Apps and products are synced for each platform, and product IDs match the stores. * [ ] The intended products, default selection, and trial states are attached and published. * [ ] Each workflow trigger, targeting rule, and fallback points to the intended paywall. * [ ] Analytics and revenue integrations are receiving test events. ## Check the paywall * [ ] Design, copy, products, and pricing match the approved experience. * [ ] Purchase, close, restore, and second-tier actions work. * [ ] Trial states, variables, user attributes, and custom actions work when used. * [ ] Product selection and purchase use separate actions so a user cannot buy the wrong product. * [ ] Check a few currencies, every supported language, a small phone, and dark mode when relevant. * [ ] The paywall opens without visual flashes or broken animations. ## Test on device * [ ] Use the intended TestFlight or Android build on a physical device for each platform. * [ ] Open every launch-critical trigger and confirm the correct paywall appears. * [ ] Complete a sandbox purchase and confirm the correct product is purchased and access unlocks. * [ ] Confirm cancel and restore behavior work. * [ ] Confirm the purchase and entitlement appear in your analytics or revenue system. * [ ] Confirm a current fallback paywall appears when Helium configuration cannot load. ## Ready to launch * [ ] The release build uses the correct Helium environment and API key. * [ ] Open issues are documented and the final paywalls are approved. * [ ] Start with a small group of users using the [Helium rollout guide](/guides/rolling-out-helium). # How Helium Works Source: https://docs.tryhelium.com/guides/how-does-helium-work The terms and the request flow behind Helium: paywalls, workflows, triggers, audiences and experiments, and how the SDK fetches and shows a paywall. A general overview of how the Helium platform works. # Useful Terms > [card] [Paywall](https://app.tryhelium.com/paywalls) > > A visual display that contains subscription options and in-app purchases. Design paywalls using AI in your Helium dashboard. > [card] [Workflow](https://app.tryhelium.com/workflows) > > A configuration that defines which paywall to show to a user, with options for targeting and experiments. > [card] [Trigger](https://app.tryhelium.com/workflows) > > An identifier used in your mobile app integration to determine which workflow to use when displaying a paywall. One workflow can have multiple triggers. > [card] [Targeting & Audiences](https://app.tryhelium.com/targeting) > > An "audience" is a segment of users that you define based on dimensions such as language, age, etc. Workflows can show different paywalls to different audiences. > > Your mobile app integration can define custom "user traits" for use in targeting. > [card] [Experiments](https://app.tryhelium.com/experiments) > > An experiment is an A/B/n test that allows you to compare paywall A versus paywall B for a specific audience. # How do paywalls get displayed on my app? This is an overview of how paywalls are actually served to users. ```mermaid theme={null} flowchart LR A([📱 App Initializes Helium SDK]) --> Server subgraph Server ["☁️ Helium Server"] direction TB B[For Each Workflow] --> C[Apply Targeting] C --> D[Resolve Experiment] D --> P[Determine Paywall for Each Trigger] end Server --> E([📲 Helium SDK Prepares Paywalls]) E --> F([🎬 App Calls 'Present Paywall' for Trigger]) F --> G([✅ Mobile SDK Displays Paywall]) style Server fill:#e8f0fe,stroke:#4a90d9,stroke-width:1.5px style A fill:#d4edda,stroke:#28a745,color:#000 style E fill:#d4edda,stroke:#28a745,color:#000 style F fill:#fff3cd,stroke:#ffc107,color:#000 style G fill:#cce5ff,stroke:#004085,color:#000 ``` # How Helium Guarantees Performance Source: https://docs.tryhelium.com/guides/how-helium-guarantees-performance How Helium keeps paywalls fast and always available: payload preloading on app open, edge caching, on-device bundle caching and the fallback system. ## TL:DR * **Helium Pre-Loads Paywalls on App Open**:The SDK pulls one payload containing metadata and bundles for every paywall in the current configuration, served from globally distributed edge regions with server-side caching. * **Paywalls render almost instantly**: Images are inlined directly into the bundles and the bundles have been heavily optimized for unobservable rendering times. P50 time-to-first-paint is 20ms. * **On-device caching:** Paywalls are cached on-device, enabling near-realtime loading for subsequent app opens — Helium just fetches the user’s paywallIDs and downloads any new bundles or updates. * **Helium will always show a paywall**: Helium’s fallback system ensures that users will always see a paywall. It lets you configure client-side paywall(s), including native experiences or downloads of Helium paywalls that will show if the paywall hasn’t loaded before presentation. * **Equivalent Conversion to Native**: We run A/A comparison tests during enterprise-scale rollouts and consistently show no degradation when compared to native experiences. ## Helium Pre-Loads Paywalls on App Open → Learn more about [initialization](https://docs.tryhelium.com/sdk/quickstart-ios#initialize-helium) When the host app launches, the Helium SDK fetches a single payload containing presentation metadata and the bundles, which are served from the Cloudflare Global CDN with tiered caching, for every paywall in the current configuration. One request gives the app everything it needs to render any paywall for the rest of the session. Requests are served from globally distributed edge regions, so users hit a nearby server regardless of geography. Payloads are cached server-side and invalidated on configuration changes, which keeps origin load low and response times tight: p50 \~300ms, p95 \~700ms (measured globally). The SDK also caches the bundles from the last-known-good payload on-device — This enables us to reduce loading times to near-0 (including for assets) for subsequent app opens, only loading updated or incremental paywalls. Quick blurb on example initialization: ```swift theme={null} @main struct MyApp: App { init() { //*** Add this: configureHelium() } var body: some Scene { WindowGroup { ContentView() } } //*** And this: private func configureHelium() { Helium.shared.initialize(apiKey: "helium-api-key") } } ``` ## Paywall Presentation is Near-Realtime → Learn more about [paywall presentation](https://docs.tryhelium.com/guides/ways-to-show-paywall) Paywalls render inside an internal presentation system tuned for fast first paint. Bundles are kept lean and self-contained: images are inlined directly into the bundle wherever feasible, eliminating the post-load flashes and layout shifts that plague typical webview paywalls. Remaining large media including video is served from Cloudinary’s global CDN with aggressive cache headers, so repeat presentations are effectively instant. The bundles themselves are served through Cloudflare with caching configured at the edge, giving us **p50 \~20ms / p95 \~500ms** time-to-first-paint globally (per Cloudflare's RUM). If a bundle fails to load entirely, the SDK falls back to a specified fallback bundle or fallback behavior. Either way, a user who triggers a paywall sees a paywall. ```swift theme={null} HeliumPaywall( trigger: "onboarding" ) { paywallNotShownReason in Text("Your native paywall here") } ``` ## Helium’s Fallback System Ensures Users Always See Paywalls → Learn more about [fallbacks](https://docs.tryhelium.com/guides/fallback-bundle) The Helium SDK does its best to fetch and display the latest paywalls in your app. In the rare case a paywall isn't ready, Helium falls back gracefully to your pre-configured client-side experience. Fallback logic is extremely flexible, allowing you to configure fallbacks conditionally based on the presentation location or other segmentation details. You can bundle downloaded copies of your actual Helium paywalls into your app to serve as fallbacks, or define native screens and custom behaviors instead. If a customer wants to prioritize server-driven paywalls, they can also configure a loading budget. This allows the SDK to present a shimmer loading experience for an SDK-configured time (e.g. 100 to 750ms) to allow the paywalls to load before presentation, or present the fallback if the allotted time completes. *** Helium is committed to growing customers conversions, and we know that sits on top of being the most performant paywall provider in the world. If you have any other questions, feel free to email [support@tryhelium.com](mailto:support@tryhelium.com) # Using the Helium Paywall Editor Source: https://docs.tryhelium.com/guides/makingpaywalls How to create and edit paywalls in the Helium dashboard: templates, screenshot import, the AI prompt bar, the element editor, products and publishing. A fast, visual way to design, test, and ship mobile paywalls—without waiting on app releases. This guide covers how to get into the editor, what each panel and tool does, and how to use the prompt bar + AI to go from idea to live experiment in minutes. *** ## Video walkthrough [Editor Loom](https://www.loom.com/embed/ebc6d71e51514722bce2f4352a3a4059?sid=22f325a5-c603-40d3-afc3-16d0b7866c25) ## 1) Entry points: creating your first paywall You have three ways to begin after clicking "New Paywall": ### A) Start from a template (simplest) 1. Click **New Paywall** → **Template** 2. Pick a template (single screen, comparison table, trial-first, hero img) 3. Connect the **Products** you want to offer 4. Click **Create**. You’ll land directly in the editor with editable text, images, and pricing placeholders **Best for:** getting something on-brand and testable in under 5 minutes. *** ### B) Start from a screenshot (AI Agent) 1. Click **New Paywall** → **From Screenshot**. 2. Upload 1 (or more!) screenshots from your app (or a paywall you love) 3. (optional but recommended): Link a public Figma file of the paywall so the agent can get fonts, colors and spacing 4. Add any additional instructions for the agent into the description field, such as brand guidelines, colors to use, and interactive behavior 5. Connect your **Products** 6. The AI reconstructs the design into a ready-to-use paywall 7. Use the **Prompt Bar** or **Element Editor** to tweak copy, styles, and structure **Best for:** cloning your current paywall or riffing on inspiration from other apps. *** ### C) Start from scratch (advanced) 1. Click **New Paywall** → **From Scratch** 2. Connect your **Products** 3. Build the paywall from the ground up from a prompt 4. Use the **Prompt Bar** to accelerate copy and layout **Best for:** bespoke designs. Most teams move faster starting from a template or screenshot. *** ## 2) Editor layout and tools The editor is split into three areas: ### Left: AI Paywall Editor * **Prompt Bar:** Natural-language commands to change copy, layout, colors, spacing, CTAs, and more. * **Chat History:** View your chat history from the current session * **Undo/Redo:** Toggle between old and new versions to view changes live — whichever version you are currently looking at is the one that the AI editor will make changes to! * **Paywall Settings:** Toggle between AI models, we recommend Claude Sonnet for general use, and GPT 5 for very large changes ### Middle: Canvas & Toolbar (live preview) * **Canvas:** Pixel-accurate rendering of your paywall as it will appear in-app (pulled OTA via the SDK). * **Toolbar (bottom):** * **Viewports:** Preview common device sizes to ensure your paywall is optimized and working on all phone sizes. * **Zoom:** Inspect fine details or zoom-to-fit. * **Dark Mode:** View light/dark. **No configuration needed—Helium auto-generates dark styles!** * **Reset Preview State:** Returns any multi-step/onboarding flow to the start. Essential when building complex onboarding experiences. * **Action Logging:** View tap and navigation events made in the preview. Actions, like Restore, Dismiss, Subscribe are **preconfigured** for you—but great for QA. * **Localization Preview:** Price localization, including discount calculations and other math are **preconfigured** for you! But you can view various locales to verify copy, currency formats, etc. * **Safe Areas:** Overlay device safe areas (notches, home indicator). Use this to ensure sticky CTAs and headers aren’t clipped. * **Element Editor:** Precise, last-mile visual edits—colors, fonts, sizes, weights, spacing, radii, shadows, alignment, and visibility by breakpoint. > **Note**\ > All changes are delivered over-the-air via the SDK—no app release required. Use **Targeting** + **Experiments** to safely ship and measure impact. ### Top: quick actions The top bar gives you fast access to the most common actions for configuring your paywall/onboarding flow. 1. **QR code preview**\ Once you’ve initialized Helium and enabled deep links, click the **QR** button to generate a scannable code. Scan on any device to open this exact paywall (and step) in your app for true on-device QA. Great for checking typography, animations, purchase sheet handoff, and safe-area behavior on real hardware. 2. **Products & Paywall config**\ Attach or change the products associated with this paywall, set the **default product selection** (e.g., annual vs monthly), and edit the **title/description** that appear next to prices. This is the fastest way to wire pricing without leaving the editor. (You can still use **Offers** on the right panel for deeper setup.) 3. **Configure “Second Try” flow**\ Show a different paywall if the user: * **Dismisses** the paywall (closes it), or * **Cancels** at the system purchase sheet (closes it after initiating). Use this to present a lighter variant, alternate framing, or a different offer on the second attempt. Pick the trigger(s), choose the follow-up paywall, and save. 4. **Save / Save as copy** * **Save** updates the server version and pushes the changes OTA via the SDK. * **Save as copy** creates a new **Variant** (ideal for experiments). 5. **Reset (to last saved)**\ Discards any unsaved edits and reloads the server state from your **last Save**.\ *Note:* This is different from **Reset Preview State** in the canvas toolbar, which only resets the internal paywall state back to its initial state. now for the fun part... ## Prompting: In Helium, you don't have to manually change colors or adjust margins. Describe the outcome in plain English; the editor generates code diffs and updates your paywall instantly. From idea → preview → **Save** (or **Save as copy**) in a single prompt. **What a single prompt can do:** * **Reshape the entire flow:** Switch single → two-step, insert/remove sections (hero, social proof, FAQs, benefits), reorder blocks, or convert to an onboarding experience—no manual wiring. * **Update visual identity:** Apply brand colors, update typography scale, tighten/loosen spacing rhythm, adjust radii/shadows/gradients, and swap imagery or icons across the layout in one prompt. * **Add more screens:** Create entire new screens for the user, like an onboarding survey, a multi-step product intro with Lottie files, all with custom transitions. * **Structure pricing UI:** Set the default plan (e.g., annual), show/hide monthly, add badges like “Save 42%” and “Most popular,” or add contextual notes beneath plans—all generated in one pass. * **Product-aware edits:** Create copy or visuals that directly refer to the selected product price, period, or discount. * **Offer-specific variants:** Create variants that only apply to users with introductory offers, highlighting reduced pricing, or trial length, while leaving the standard paywall the same. * **Add new components:** Customer testimonials, feature comparisons, * **Incorporate Uploaded Images/Icons:** The editor will be able to see and incorporate any assets you upload such as icons, logos, hero images, or even Lottie animations. * **Match a Visual Reference:** Upload an image example of a component or paywall you like, and the editor will build based on the image. * **Animations:** Simply describe the behavior you want, and voila! **Examples you can paste** * “Animate the testimonial carousel, have it automatically scroll to the next state if the user hasn't touched it for 5 seconds” * "Add a 5 question \*\*onboarding survey \*\*with the same visual styles, and customize the final paywall based on if the user is high or low intent, offering our annual plan for high-intent users and weekly for low-intent users." * “Apply brand colors (primary #0A84FF), make headings semibold, tighten vertical spacing \~12%, and keep the CTA sticky.” * “Reference the user's timezone and display a countdown timer to the end of the day when the offer expires" We’re excited to see what you build—have fun with it! We’d love your feedback at [**support@tryhelium.com**](mailto:founders@tryhelium.com). # Paddle Onboarding Guide Source: https://docs.tryhelium.com/guides/paddle-onboarding-guide Step-by-step Paddle setup for App2Web: account, payment link, connecting Paddle to Helium, building paywalls, adding web checkout to your app, entitlements, testing and rollout. Take users from your paywall to web checkout, then back to your app with access unlocked. ## 1. Set up your Paddle account 1. Complete Paddle’s [account setup](https://developer.paddle.com/build/onboarding/set-up-checklist#sign-up), including identity verification, banking, and tax details, to enable live payments. 2. [Create your products and prices](https://developer.paddle.com/build/products/create-products-prices) in Paddle. ## 2. Set up the payment link 1. Go to [Paddle website approval](https://vendors.paddle.com/request-domain-approval) and add a new domain. 2. Go to [Paddle Checkout Settings](https://vendors.paddle.com/checkout-settings) and find the **Default payment link** section. Paste in the same domain you just added for **Paddle website approval**. 3. On the same page, enable **Apple Pay** under **Payment Methods**. ## 3. Connect Paddle to Helium Go to **Settings → Integrations → Paddle** in the [Helium dashboard](https://app.tryhelium.com/integrations) and follow the instructions there to connect your account. Helium configures the webhook automatically. **Sync your products.** In the Helium dashboard, click **Sync Products**. Your Paddle products and prices will appear alongside your iOS products and can be added to paywalls. > [accordion] Optional: add free trials > > **Each trial price needs a linked non-trial price.** > > 1. Create a trial price and a matching non-trial price in Paddle, then sync them to Helium. > 2. Link the trial and non-trial prices in Helium so the paywall can offer the appropriate purchase option. > 3. Use a **separate non-trial price for every trial offer** you launch—even if the amount is the same. This lets you identify which offer a non-trial purchase came from. > > Helium limits trials to one per customer, including after cancellation. Trials require a payment method up front. ## 4. Build your paywalls Your in-app paywall opens a linked web paywall when the user purchases a Paddle product. The user completes payment in the browser, then returns to your app. 1. Add your Paddle product(s) to your in-app paywall. Include iOS products for the in-app purchase option. 2. Create a hosted web paywall and link it to your in-app paywall. 3. Publish both paywalls. Target the **in-app paywall** to eligible users; the hosted paywall cannot be added directly to workflows or experiments. See [Build an App2Web paywall](/guides/build-app2web-paywall) for the walkthrough. > [accordion] Supported platforms and languages > > App2Web is iOS-only and limited to US storefronts. Hosted paywalls currently support one language. On Android, the React Native and Flutter web-checkout APIs are safe no-ops; keep your regular IAP flow. ## 5. Add web checkout to your app Choose your SDK, then enable checkout, identify your user, handle the return link, and add subscription management. Your app needs a [custom URL scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) or [universal link](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) so checkout can return users to it. > [tab] iOS (native, Helium 4.6.0+) > > **Enable checkout before initializing Helium:** > > ```swift theme={null} > Helium.config.enableExternalWebCheckout( > redirectURL: "yourapp://openapp", > paymentProcessors: .paddle > ) > ``` > > Set up a deep link in your app, then use it as `redirectURL`. Checkout returns here after success, cancellation, or failure. > > **Set your user ID on Helium** before showing a paywall. > > > [accordion] Purchases before sign-in > > > > If you must set the user ID after showing a paywall, set `allowWebCheckoutWithoutUserId` to `true`. > > **Handle the return link.** Forward incoming links to `Helium.shared.handleURL(url)` from your `onOpenURL` / `application(_:open:)` handler. > > **Add a "Manage Subscription" button** so users can cancel or update payment methods via Paddle's customer portal: > > ```swift theme={null} > if await Helium.entitlements.hasActivePaddleEntitlement() { > // show the manage subscription button > } > > // when the button is tapped: > do { > let url = try await Helium.shared.createPaddlePortalSession() > UIApplication.shared.open(url) > } catch { > print("Failed to open customer portal: \\(error)") > } > ``` > > The portal opens `paddle.net` for subscription management. Cancellation emails use the [checkout billing email](/guides/app2web-faq#billing-email). > > > [accordion] Optional: pre-authenticated portal links > > > > To open a pre-authenticated customer portal session, generate the link from your backend instead. Look up the user's Paddle customer ID with Helium: > > > > ```swift theme={null} > > let paddleCustomerId = await Helium.shared.getPaddleCustomerId() > > ``` > > > > Send that ID to your server and follow [Paddle's guide for generating pre-authenticated customer portal links](https://developer.paddle.com/build/customers/integrate-customer-portal/). > [tab] React Native / Expo > > Available in `expo-helium` 3.4.13+ and `@tryheliumai/paywall-sdk-react-native` 3.1.2+. > > **Enable checkout before initializing Helium:** > > ```tsx theme={null} > enableExternalWebCheckout({ > redirectURL: "yourapp://openapp", > paymentProcessors: ["paddle"], > }); > ``` > > Set up a deep link in your app, then use it as `redirectURL`. Checkout returns here after success, cancellation, or failure. > > **Set your user ID on Helium** before showing a paywall. > > > [accordion] Purchases before sign-in > > > > If you must set the user ID after showing a paywall, call `setAllowWebCheckoutWithoutUserId(true)`. > > **Handle the return link.** Forward incoming links to `heliumHandleURL(url)` from your deep link handling: > > ```tsx theme={null} > useEffect(() => { > const sub = Linking.addEventListener('url', (event) => heliumHandleURL(event.url)); > void Linking.getInitialURL().then(heliumHandleURL); > return () => sub.remove(); > }, []); > ``` > > > [!NOTE] > > > > With **Expo Router**, you may need to [override the default behavior](https://docs.expo.dev/router/advanced/native-intent/#sending-navigation-events-to-third-party-services). > > **Add a "Manage Subscription" button** so users can cancel or update payment methods via Paddle's customer portal: > > ```tsx theme={null} > if (await hasActivePaddleEntitlement()) { > // show the manage subscription button > } > > // when the button is tapped: > const url = await createPaddlePortalSession(); > if (url) { > await Linking.openURL(url); > } > ``` > > The portal opens `paddle.net` for subscription management. Cancellation emails use the [checkout billing email](/guides/app2web-faq#billing-email). > > > [accordion] Optional: pre-authenticated portal links > > > > To open a pre-authenticated customer portal session, generate the link from your backend instead. Look up the user's Paddle customer ID with Helium: > > > > ```tsx theme={null} > > const paddleCustomerId = await getPaddleCustomerId(); > > ``` > > > > Send that ID to your server and follow [Paddle's guide for generating pre-authenticated customer portal links](https://developer.paddle.com/build/customers/integrate-customer-portal/). > [tab] Flutter (Helium 3.3.8+) > > **Enable checkout before initializing Helium:** > > ```dart theme={null} > await HeliumFlutter().enableExternalWebCheckout( > redirectURL: "yourapp://openapp", > paymentProcessors: {HeliumWebCheckoutProcessor.paddle}, > ); > ``` > > Set up a deep link in your app, then use it as `redirectURL`. Checkout returns here after success, cancellation, or failure. > > > [accordion] Register a Flutter deep link > > > > For a custom scheme, add a `CFBundleURLTypes` entry to `ios/Runner/Info.plist`: > > > > ```xml theme={null} > > CFBundleURLTypes > > > > > > CFBundleURLName > > com.yourcompany.yourapp > > CFBundleURLSchemes > > > > yourapp > > > > > > > > ``` > > > > To use a universal link (`https://...`) instead, set up [associated domains](https://docs.flutter.dev/ui/navigation/deep-linking) and use that URL as the `redirectURL`. > > **Set your user ID on Helium** before showing a paywall. > > > [accordion] Purchases before sign-in > > > > If you must set the user ID after showing a paywall, call `setAllowWebCheckoutWithoutUserId(true)`. > > **Handle the return link.** Forward incoming links to `handleURL(url)`; Helium ignores unrelated URLs. If you don’t already handle deep links, add [app_links](https://pub.dev/packages/app_links) with `flutter pub add app_links`: > > ```dart theme={null} > import 'package:app_links/app_links.dart'; > > _linkSubscription = AppLinks().uriLinkStream.listen((uri) { > HeliumFlutter().handleURL(uri.toString()); > }); > ``` > > > [!NOTE] > > > > `uriLinkStream` also emits the link that launched the app, so cold starts are covered — there is no separate initial-link step. If you use `app_links`, set `FlutterDeepLinkingEnabled` to `false` in `Info.plist` so Flutter's built-in deep-link handling doesn't consume the link first. > > **Add a "Manage Subscription" button** so users can cancel or update payment methods via Paddle's customer portal. `launchUrl` comes from the [url_launcher](https://pub.dev/packages/url_launcher) package: > > ```dart theme={null} > final hasPaddle = await HeliumFlutter().hasActivePaddleEntitlement(); > if (hasPaddle) { > // show the manage subscription button > } > > // when the button is tapped: > final urlString = await HeliumFlutter().createPaddlePortalSession(); > if (urlString != null) { > await launchUrl(Uri.parse(urlString)); > } > ``` > > The portal opens `paddle.net` for subscription management. Cancellation emails use the [checkout billing email](/guides/app2web-faq#billing-email). > > > [accordion] Optional: pre-authenticated portal links > > > > To open a pre-authenticated customer portal session, generate the link from your backend instead. Look up the user's Paddle customer ID with Helium's `getPaddleCustomerId()`, send it to your server, and follow [Paddle's guide for generating pre-authenticated customer portal links](https://developer.paddle.com/build/customers/integrate-customer-portal/). Helium can predict when users are likely to have Apple Pay billing issues and, when you use the App2Web eligibility preset, prevents them from seeing web payments. If you’d like to turn off this feature, use the setting below **before initializing Helium**: > [accordion] Turn off web billing issue detection > > > [tab] iOS > > > > ```swift theme={null} > > Helium.config.enableWebApplePayReadiness = false > > ``` > > > [tab] Expo / React Native > > > > ```tsx theme={null} > > setEnableWebApplePayReadiness(false); > > ``` > > > > React Native requires `@tryheliumai/paywall-sdk-react-native` 3.1.14+. On 3.1.13, set the native iOS flag in `AppDelegate` before JavaScript initializes Helium. This is a no-op on Android. > > > [tab] Flutter > > > > ```dart theme={null} > > await HeliumFlutter().setEnableWebApplePayReadiness(false); > > ``` > > > > Requires `helium_flutter` 3.3.15+. On 3.3.14, set the native iOS flag in `AppDelegate` before Dart initializes Helium. This is a no-op on Android. ## 6. Configure your entitlements Helium can check web subscription access in one line: > [tab] iOS > > ```swift theme={null} > let hasWebAccess = await Helium.entitlements.hasActivePaddleEntitlement() > ``` > [tab] React Native / Expo > > ```tsx theme={null} > const hasWebAccess = await hasActivePaddleEntitlement(); > ``` > [tab] Flutter > > ```dart theme={null} > final hasWebAccess = await HeliumFlutter().hasActivePaddleEntitlement(); > ``` Use this result alongside your existing in-app purchase checks to unlock paid features. Helium updates the entitlement after purchase and tracks subsequent subscription changes through the automatically configured webhook. Already have an entitlement system? You can connect it instead: > [accordion] Use RevenueCat for entitlements > > Connect Paddle purchases to your existing RevenueCat entitlements: > > 1. Create a Paddle web configuration in the [RevenueCat dashboard](https://app.revenuecat.com). > 1. Select your project > **Web** > Add web provider > Paddle > 2. Create a new [Paddle API Key](https://vendors.paddle.com/authentication-v2) for RevenueCat. **See permissions below** > 3. Paste in the new Paddle API key > 4. Purchase tracking should be **Automatic** > 5. Under **App user ID matching** select **Use a custom field** with `rc_user_id` as the field key > > 2. Go to **Product catalog** > **Products** and Import your Paddle products into RevenueCat. > > 3. Attach those products to desired entitlement(s). > > > [accordion] Permissions for Paddle API Key that RevenueCat needs > > > > * Addresses  `READ` > > * Adjustments - `READ` > > * Businesses - `READ` > > * Client-side tokens - `WRITE` > > * Customer portal sessions - `WRITE` > > * Customers - `READ` > > * Discounts - `READ` > > * Notification settings - `WRITE` > > * Notifications - `READ` > > * Payment methods - `READ` > > * Prices - `READ` > > * Products - `READ` > > * Subscriptions - `READ` > > * Transactions - `WRITE` > > RevenueCat can take a few seconds to reflect a purchase. Check Helium entitlements as well to unlock access immediately while RevenueCat syncs. > > > [accordion] Troubleshooting RevenueCat Entitlements for Paddle Purchases > > > > * Make sure you have done the above steps and include all of your Paddle products in your RevenueCat entitlements. > > * Find your Paddle -> RevenueCat webhook at [https://vendors.paddle.com/notifications-v2](https://vendors.paddle.com/notifications-v2) and click on it to see that notifications are being sent successfully. If you see errors, you may need to adjust the permissions on the Paddle API Key you provided to RevenueCat. > > * If you still have issues, delete the existing Paddle web provider in RevenueCat, revoke the Paddle API Key you created for RevenueCat (leave the Helium one), and run through the above steps again. > [accordion] Use your own entitlement system > > Keep your backend as the source of truth. Connect Paddle webhooks to your system, link the Paddle customer and subscription to your app user, and update access when the subscription changes. > > Follow [Paddle’s guide to provisioning access](https://developer.paddle.com/build/subscriptions/provision-access-webhooks/). ## 7. Test everything Create a test audience with **Paddle eligible users** and the **`sandbox` or `debug` app environment**. Target your in-app App2Web paywall to it. You can also test via **[Helium’s triple-tap flow](/guides/paywall-previews#preview-paywalls-from-your-app)**: open a Helium paywall in your test build, triple-tap it, and select your App2Web paywall. [App2Web previews](/guides/app2web-previews) support simulated checkout to check the flow without a charge; simulated purchases do not grant entitlements. Real checkout charges the payment method and lets you verify access. * **Purchase:** open a real trigger → browser checkout → purchase → return to the app. Confirm access unlocks in your chosen entitlement system and `hasActivePaddleEntitlement()` returns `true`. * **Dismiss or cancel checkout:** return to the expected screen without granting access or showing success. * **Manage subscription:** open the customer portal, cancel, and confirm access lasts until period end. * **Webhooks:** confirm Paddle delivers to Helium with 2xx responses. > [accordion] If you use RevenueCat or allow purchases before sign-in > > * Confirm RevenueCat updates within a few seconds of purchase, if connected. > * If users can buy before you set a durable user ID, purchase first, then set the ID and confirm the entitlement attaches correctly. > [accordion] App2Web paywall not appearing? > > The device locale country, App Store storefront, and IP location must all be US. From the US, disable VPNs. From outside the US, use a US device region, a US sandbox Apple storefront, and a US VPN. ## 8. Roll out your experiment Finish the [App2Web go-live checklist](/guides/app2web-go-live-checklist), including a test through a real trigger. 1. **Create both audiences:** a small rollout audience with the **Paddle eligibility preset** AND `user_id_bucket <= 10`, and a full eligible audience with **just the Paddle eligibility preset**. 2. **Start the experiment:** select the small rollout audience and launch a **50/50 experiment: your current IAP paywall versus App2Web**. 3. **Monitor for 24 hours:** compare conversion rates and check checkout errors, returns to the app, and entitlement delivery. 4. **Expand when the data looks good:** use the same experiment and change its audience to the full eligible audience. Keep monitoring [experiment results](/guides/app2web-faq#experiment-results) as data comes in. The first 24 hours are a rollout health check, not a final verdict on performance. See the [App2Web FAQ](/guides/app2web-faq) for attribution, checkout behavior, and experiment results. # Paywall Previews On Device Source: https://docs.tryhelium.com/guides/paywall-previews Test any paywall you've made in Helium, on your device, in seconds. iOS 4.2.0+Android 4.4.1+React Native 3.4.1+Flutter 3.3.1+ Testing paywalls and entitlements is one of the most annoying parts of shipping an app — so we made it easy. ## Preview Paywalls from your App **Requirements:** Integrate the Helium SDK into your app and navigate to any existing Helium paywall. You will need to have already set up a valid workflow. Once you are viewing a paywall, **triple tap** anywhere on the paywall to bring up a list of all your paywalls — you can view the latest published version or latest draft version. Triple tap again or dismiss the paywall to return to the list of paywalls. ![Triple tap to open Paywall Previews](https://mintcdn.com/helium/TLVewIOgiGu9osCK/images/paywall-previews-triple-tap.gif?s=372eff9fca412a484a1a770f14d4d3e7) > [!NOTE] > > By default, this functionality is only enabled in debug/TestFlight builds for iOS and debug builds for Android. ## Second Try Paywalls If a paywall has a second try offer configured, the preview includes it: the second try paywall shows on dismiss or on purchase cancel, depending on its configuration, with its own products and prices. Second try is not supported on App2Web paywalls. ## App2Web previews Available on iOS with these minimum SDK versions: * Expo / React Native using `expo-helium`: **3.6.0+** * React Native using `@tryheliumai/paywall-sdk-react-native`: **3.1.10+** * Flutter (`helium_flutter`): **3.3.12+** * Native iOS: **4.9.0+** Previewing an App2Web paywall runs the full app-to-web checkout flow. Real purchases require an [eligible US device](/guides/app2web-previews#purchase-eligibility); other devices simulate purchases. See [App2Web Paywall Previews](/guides/app2web-previews). ## Preview Paywalls from the Helium App (coming soon) *Not yet available.* A standalone Helium app on the Apple App Store and Google Play Store where you can log in and view your paywalls. # Paywall Traits Source: https://docs.tryhelium.com/guides/paywall-traits Pass values from your app into a paywall at presentation time so one paywall can change copy, pricing or behavior per user. Covers the editor setup and the SDK call for each platform. iOS 4.4.2+Android 4.4.2+React Native 3.4.3+Flutter 3.3.3+ Paywall traits are values passed into a paywall upon presentation, allowing your paywall to display or behave differently depending on those values. This must be configured in two places: 1. Your paywall via the paywall editor 2. Your app by passing in values to the Helium mobile SDK ## Paywall Editor ![Paywall Traits](https://mintcdn.com/helium/RB3DV7v6472dGP3j/images/paywall_traits.jpg?fit=max\&auto=format\&n=RB3DV7v6472dGP3j\&q=85\&s=66de8518779a10c2d1eb248391567873) Open the paywall editor from the [Helium dashboard](https://app.tryhelium.com/paywalls). Type something like ```text theme={null} use a paywall trait with key "name" to display a customized greeting ``` > [!WARNING] > > You MUST provide a **default value** or behavior for each trait, in case the app does not pass in a value. ## Pass in from the SDK By default, user traits will automatically be included as custom paywall traits in all of your paywalls. (Just make sure your SDK version is higher than what's listed at the top of this page.) To pass in additional paywall traits during paywall presentation, use the `customPaywallTraits` parameter. ```swift iOS theme={null} Helium.shared.presentPaywall( trigger: "your-trigger", config: PaywallPresentationConfig( customPaywallTraits: HeliumUserTraits(["name": nameValue]) ) ) { paywallNotShownReason in } ``` ```kotlin Android theme={null} import com.tryhelium.paywall.core.HeliumUserTraits.Companion.create Helium.presentPaywall( "your-trigger", config = PaywallPresentationConfig( customPaywallTraits = mapOf( "name" to nameValue, ).create() ) ) ``` ```tsx React Native theme={null} presentUpsell({ triggerName: "your-trigger", customPaywallTraits: { name: nameValue }, }); ``` ```dart Flutter theme={null} await HeliumFlutter().presentUpsell( context: context, trigger: "your-trigger", customPaywallTraits: { "name": nameValue }, ); ``` ## Targeting and Metrics Considerations If you want to evaluate the effects of different traits in your paywall, utilize user traits in your SDK integration. Helium does not currently support the use of`customPaywallTraits` (passed during paywall presentation) as metrics filters. User traits can also be used for targeting. ### **What if I set both?** If the same key is present in both user traits and `customPaywallTraits`, the paywall will see the value from `customPaywallTraits`. Metrics still only sees the value from user traits. ## Coming Soon We are working on adding default traits you can use without passing in from SDK. # Promotional Offers Source: https://docs.tryhelium.com/guides/promotional-offers Show App Store promotional offers to existing or lapsed subscribers by combining entitlement checks, paywall traits and a custom purchase delegate. > [card] Promotional Offer > > An offer on a subscription for users who already have an active subscription in the same subscription group or previously had a subscription in the subscription group. *This guide is focused on iOS although similar can be achieved with Android.* Helium does not yet officially support promotional offers. However you can implement this by doing the following: 1. Check entitlements of user to determine eligibility for the promotional offer. You can use the Helium SDK to help with this. 2. Use a paywall trait or targeting to display promotional experience in paywall. 3. Call an endpoint on your server that can [generate JWS signature](https://developer.apple.com/documentation/StoreKit/generating-jws-to-sign-app-store-requests) for promotional offer. 4. Override default Helium purchase logic to pass in the promotional offer: ```swift theme={null} // Override default StoreKitDelegate (executes purchase through StoreKit2) class MyHeliumPurchaseDelegate : StoreKitDelegate { // Available in iOS Helium SDK 4.4.3+ override func performPurchase(product: Product, productId: String) async throws -> Product.PurchaseResult { // Determine eligibility based on your business logic (e.g. server check, user state). let isEligible: Bool = true let purchaseOptions: Set = isEligible ? Set(Product.PurchaseOption.promotionalOffer("offer-id-here", compactJWS: "compact-jws-from-your-server")) : [] return try await product.heliumPurchase(options: purchaseOptions) } } // end delegate // Make sure to set purchase delegate before your initialize call Helium.config.purchaseDelegate = MyHeliumPurchaseDelegate() Helium.shared.initialize() ``` # Set Up Revenue Tracking Source: https://docs.tryhelium.com/guides/revenue-reporting Set up webhooks to track your app's revenue and subscription events. This is important if you want Helium to display subscription, revenue, and other metrics! Go to [Integrations > Revenue Tracking](https://app.tryhelium.com/integrations/revenue) to configure webhooks. ![Rev Reporting](https://mintcdn.com/helium/vjbIVTFp_dv4L6zW/images/rev-reporting.jpg?fit=max\&auto=format\&n=vjbIVTFp_dv4L6zW\&q=85\&s=5a727d069f4d286dc69bef830718bddb) ## Configure iOS Choose ONE of the following 3 options: ### 1) App Store Server Notifications > [!TIP] > > This option is recommended if you are using StoreKit to handle your purchases. Send purchase events direct from Apple to Helium. ### 2) RevenueCat Webhooks > [!TIP] > > This option is recommended if you are using RevenueCat to handle your purchases. Use RevenueCat webhooks to send revenue events to Helium. Follow the instructions shown under **RevenueCat Webhooks**. ### 3) Forward App Store Server Notifications > [!TIP] > > This option is recommended if you are using StoreKit to handle your purchases but want to consume App Store Server Notifications on your own server and forward those events to Helium. Grab the **Webhook URL** from the **App Store Server Notifications** section and use that value in your forwarding code. In your existing App Store Server Notifications handler, add a snippet that forwards the payload to Helium **unchanged**. Place it as early as possible — after you've parsed the incoming body, but before any type filtering or early returns — so that Helium receives *every* notification type, not just the subset your own handler acts on. **Don't couple your response to the forward.** Await the forward and wrap it in a `try/catch` that only logs on failure. It should never throw or change the status you return to Apple — otherwise a hiccup forwarding to Helium would make Apple retry the whole notification and re-run your own handling. Forwarding is just a POST — send the request body to your Helium Webhook URL with `Content-Type: application/json`. The examples below cover a few common stacks, but any language works. Reach out to Helium support if you have any questions. ```javascript Node/Express theme={null} // Inside your existing app.post(...) ASSN handler, near the top: try { await axios.post( 'your-helium-webhook-url-here', req.body, { headers: { 'Content-Type': 'application/json' }, timeout: 5000 } ); } catch (error) { console.error('Failed to forward webhook to Helium:', error.message); } ``` ```javascript Next.js theme={null} // Inside your existing POST handler, right after you read the body: // App Router: const body = await request.json(); // Pages Router: const body = req.body; try { const response = await fetch( 'your-helium-webhook-url-here', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(5000) } ); if (!response.ok) { console.error(`Failed to forward webhook to Helium: status ${response.status}`); } } catch (error) { console.error('Failed to forward webhook to Helium:', error); } ``` ```go Go theme={null} // Inside your existing handler, after reading the request body into `body` // (a []byte holding the raw JSON payload), near the top: func() { ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second) defer cancel() req, err := http.NewRequestWithContext(ctx, http.MethodPost, "your-helium-webhook-url-here", bytes.NewReader(body)) if err != nil { log.Printf("Failed to forward webhook to Helium: %v", err) return } req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { log.Printf("Failed to forward webhook to Helium: %v", err) return } defer resp.Body.Close() if resp.StatusCode >= 300 { log.Printf("Failed to forward webhook to Helium: status %d", resp.StatusCode) } }() ``` ```python Python w/ Flask theme={null} # Inside your existing route, near the top: try: response = requests.post( 'your-helium-webhook-url-here', json=request.json, headers={'Content-Type': 'application/json'}, timeout=5 ) response.raise_for_status() except requests.exceptions.RequestException as e: print(f'Failed to forward webhook to Helium: {e}') ``` ```python Python w/ FastAPI theme={null} # Inside your existing handler, right after you read the body: # body = await request.json() try: async with httpx.AsyncClient(timeout=5.0) as client: response = await client.post( 'your-helium-webhook-url-here', json=body, headers={'Content-Type': 'application/json'} ) response.raise_for_status() except httpx.HTTPError as e: print(f'Failed to forward webhook to Helium: {e}') ``` ## Configure Android Choose ONE of the following 2 options: ### 1) Google Play RTDN > [!TIP] > > This option is recommended if you are NOT using RevenueCat to handle your purchases. Utilize Google Play Real-Time Developer Notifications to send revenue events to Helium. ### 2) RevenueCat Webhooks > [!TIP] > > This option is recommended if you are using RevenueCat to handle your purchases. Use RevenueCat webhooks to send revenue events to Helium. Follow the instructions shown under **RevenueCat Webhooks**. # Rolling Out Helium Source: https://docs.tryhelium.com/guides/rolling-out-helium A simple guide for rolling out Helium and monitoring performance. Here are our tips for rolling out Helium smoothly. Start small, make sure the basics are working, and ramp up from there. ## Set up the rollout Use your existing feature flag or experimentation tool to split users between your current paywall and Helium. PostHog, Statsig, Firebase Remote Config, LaunchDarkly, or your own feature flag system all work. For an A/A comparison, keep the paywall design, products, targeting, and purchase behavior as similar as possible between the two groups. > [!TIP] > > Initialize Helium at app launch for all users. Use the feature flag to decide whether a user sees the current experience or Helium. ## Start small First, test with internal or allowlisted users. Confirm the paywall opens and dismisses correctly, the right products appear, purchases work, and analytics are flowing. Then roll Helium out to a small percentage of users, usually around 5%, for 24-48 hours. This is mostly a check that everything works in production. ## Validate the data At this stage, make sure: * Data is showing up in Helium * Paywall views and conversions are being recorded * Analytics are flowing for each paywall and trigger * Error logs do not show any new problems This step is about confirming the data is working, not comparing aggregate performance yet. ## Ramp up Once everything looks healthy, you can roll Helium out to everyone. If you want to confirm conversion is maintained first, move to a 50/50 split between your current experience and Helium. At that point, loosely compare the users in each rollout group, paywall views, and paywall conversion rate. Run it long enough to get a useful amount of conversion data for your traffic level, then complete the rollout. # StoreKit Testing (iOS) Source: https://docs.tryhelium.com/guides/storekit-testing This guide covers how to set up StoreKit Testing in Xcode to test paywall displays across different regions and configurations. ## Overview StoreKit Testing allows you to test in-app purchases and paywall presentations locally without connecting to App Store servers or making real purchases. > [!NOTE] > > To test your actual products across different regions, we suggest creating a sandbox test user: > > * Create one at [https://appstoreconnect.apple.com/access/users/sandbox](https://appstoreconnect.apple.com/access/users/sandbox) > * Change the **Country or Region** field for the sandbox user > * On your test device, go to Settings -> Developer and sign in to the sandbox account > * Simulator *can* work… but sometimes has issues so physical device is recommended > * Run app from Xcode and the selected storefront country should be reflected > * More details on [this page](https://developer.apple.com/documentation/storekit/testing-in-app-purchases-with-sandbox#Sign-in-to-your-Sandbox-Apple-Account-for-a-development-signed-app) ## Prerequisites * Xcode 14 or later (for synced StoreKit configuration files) * iOS 15.0+ target ## Setting Up StoreKit Testing ### 1. Create a StoreKit Configuration File 1. In Xcode, go to **File → New → File from Template...** 2. Search for and select **StoreKit Configuration File** as the file template, then click **Next** 3. Optional — check the "Sync this file with an app in App Store Connect" box to automatically configure the file with products you have already set up in App Store Connect 4. Complete the file creation flow, saving the file in the top-level folder of your project. You don't need to add it to a target. ### 2. Configure your StoreKit Configuration File **Note —** If you’ve chosen to sync your configuration file with the App Store Connect, your file will already be populated with your products. To re-sync with App Store Connect, click on the file and then Sync at the bottom-left. If you want to manually edit it, use **Editor > Convert to Local StoreKit Configuration**. Use the **+** at the bottom-left to add a product. ![Screenshot2025 05 27at12 57 55PM Pn](https://mintcdn.com/helium/rKQOIu7pMSaYpNTG/images/Screenshot2025-05-27at12.57.55PM.png?fit=max\&auto=format\&n=rKQOIu7pMSaYpNTG\&q=85\&s=c95ea3a34417ec424cfeecd3069d6e2d) Complete the form that pops up. Once created, you can edit all details of a product such as price, product ID, etc. ## Run Your App With StoreKit Testing You can either edit an existing scheme or create a new one (recommended): 1. In Xcode, go to **Product → Scheme → Manage Schemes...** 2. Select your primary scheme and find the option to **Duplicate**: ![Screenshot2025 05 27at11 49 00AM Pn](https://mintcdn.com/helium/rKQOIu7pMSaYpNTG/images/Screenshot2025-05-27at11.49.00AM.png?fit=max\&auto=format\&n=rKQOIu7pMSaYpNTG\&q=85\&s=b54b07eb94b8a039fe84c94bcee7e988) 3. Edit the new scheme's name so you know it's for StoreKit testing. 4. Select the **Run** action. 5. Click the **Options** tab. 6. For the **StoreKit Configuration** option, select a configuration file and click Close. 7. Run your project (make sure your active scheme is the one with the StoreKit Configuration option set!) An Xcode project can contain multiple StoreKit configuration files but only one can be active at a time. When it’s active, your app gets StoreKit data as defined in your configuration file instead of accessing App Store Connect or the sandbox server. ## Regional Testing Go to your StoreKit config file and under **Configuration Settings**, change **Default Storefront**: ![Screenshot2025 05 27at12 25 46PM Pn](https://mintcdn.com/helium/rKQOIu7pMSaYpNTG/images/Screenshot2025-05-27at12.25.46PM.png?fit=max\&auto=format\&n=rKQOIu7pMSaYpNTG\&q=85\&s=01992305f0bf261b27e4c34beb8f19cf) Then run your app again, and you should be able to see pricing displays for the selected region. Note that the **price numerical value will still be what is specified in the config file**, but you should see a change in currency symbols. > [!NOTE] > > Make sure you explicitly save (cmd+s) the StoreKit Configuration File before running the app — changes made here won’t get picked up otherwise! ## Additional Resources ### Test Purchases For more complex purchase flows with StoreKit Testing, refer to Apple's documentation on the [transaction manager](https://developer.apple.com/documentation/xcode/testing-in-app-purchases-with-storekit-transaction-manager-in-code). ### Other Ways to Test Across Regions 1. Use Xcode and your sandbox account. You can [change the region of your sandbox account](https://developer.apple.com/documentation/storekit/testing-in-app-purchases-with-sandbox#Test-In-App-Purchases-for-all-regions). Make sure you have disabled StoreKit Testing for this. 2. On a TestFlight build, you can [use your sandbox account as well](https://developer.apple.com/documentation/storekit/testing-in-app-purchases-with-sandbox#Sign-in-to-your-Sandbox-Apple-Account-for-a-TestFlight-app), but only do this on a dedicated testing device! ### Automated Testing You can utilize StoreKit Testing in your continuous integration tests. See Apple's documentation [here](https://developer.apple.com/documentation/StoreKitTest) and a more detailed testing overview [here](https://developer.apple.com/documentation/StoreKit/testing-at-all-stages-of-development-with-xcode-and-the-sandbox). # Testing Your Paywalls Source: https://docs.tryhelium.com/guides/test-paywalls Preview any paywall on device via deep links before it is live. ## Test Via Deep Links Once you get this set up, you'll be able to scan a QR code from the Helium dashboard and have that paywall show on your device! > [tab] iOS > > ### Step 1: Add URL Scheme > > Open your project in Xcode and add a URL scheme ([official Apple documentation here](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)): > > 1. Select your app target > 2. Go to **Info** tab > 3. Expand **URL Types** section > 4. Click **+** to add a new URL type > 5. Set **URL Schemes** to: `helium-test` > 6. Set **Identifier** to your bundle ID (e.g., `com.company.myapp`) > > ![New Scheme Pn](https://mintcdn.com/helium/rKQOIu7pMSaYpNTG/images/new-scheme.png?fit=max\&auto=format\&n=rKQOIu7pMSaYpNTG\&q=85\&s=465abe57a2814776609adb7485ee7c73) > > ### Step 2: Handle Deep Links > > Add the following to handle incoming test links: > > ```swift SwiftUI theme={null} > import Helium > > @main > struct MyApp: App { > var body: some Scene { > WindowGroup { > ContentView() > .onOpenURL { url in > Helium.shared.handleDeepLink(url) > } > } > } > } > ``` > > ```swift SceneDelegate theme={null} > import Helium > > class SceneDelegate: UIResponder, UIWindowSceneDelegate { > func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { > Helium.shared.handleDeepLink(URLContexts.first?.url) > } > } > ``` > > ```swift AppDelegate theme={null} > import Helium > > class AppDelegate: UIResponder, UIApplicationDelegate { > func application(_ app: UIApplication, > open url: URL, > options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { > return Helium.shared.handleDeepLink(url) > } > } > ``` > [tab] React Native > > ### Step 1: Add URL Scheme > > Add the following to your **app.json** or **app.config.js**: > > ```json theme={null} > { > "expo": { > "scheme": "helium-test" > } > } > ``` > > > [!NOTE] > > > > If you already have a scheme set, you can switch to a list format: `"scheme": ["my-scheme", "helium-test"]` > > ### Step 2: Handle Deep Links > > Add the following to your main App component > > ```typescript theme={null} > import { useEffect } from 'react'; > import * as Linking from 'expo-linking'; > import { handleDeepLink } from '@tryheliumai/paywall-sdk-react-native'; > > export default function App() { > useEffect(() => { > // Handle deep links when app is already open > const subscription = Linking.addEventListener('url', (event) => { > handleDeepLink(event.url); > }); > > // Handle deep link that opened the app > Linking.getInitialURL().then((url) => { > handleDeepLink(url); > }); > > return () => subscription.remove(); > }, []); > > // Rest of your app > return ; > } > ``` > [tab] Flutter > > ### Step 1: Add URL Scheme > > Add the following to `ios/Runner/Info.plist`: > > ```html theme={null} > CFBundleURLTypes > > > CFBundleURLSchemes > > helium-test > > CFBundleURLName > com.example.myapp > > > ``` > > > [!NOTE] > > > > Replace `com.example.myapp` with your bundle ID. > > ### Step 2: Handle Deep Links > > Install the [**app_links**](https://github.com/llfbandit/app_links) package by running: > > ```shellscript theme={null} > flutter pub add app_links > ``` > > Or by running `flutter pub get` after adding directly to `pubspec.yaml`: > > ```yaml theme={null} > dependencies: > app_links: ^6.4.1 > ``` > > Then in your root app widget: > > ```dart theme={null} > // for StreamSubscription > import 'dart:async'; > // for app_links and Helium > import 'package:app_links/app_links.dart'; > import 'package:helium_flutter/helium_flutter.dart'; > > > class MyApp extends StatefulWidget { > @override > _MyAppState createState() => _MyAppState(); > } > > class _MyAppState extends State { > StreamSubscription? _linkSubscription; > > @override > void initState() { > super.initState(); > > // Add code to instantiate AppLinks > _linkSubscription = AppLinks().uriLinkStream.listen((uri) { > HeliumFlutter().handleDeepLink(uri.toString()); > }); > } > > @override > void dispose() { > // Good practice, though not strictly necessary for root widget > _linkSubscription?.cancel(); > super.dispose(); > } > > // Rest of your app > } > ``` > [!TIP] > > `handleDeepLink` will return true if the test paywall was successfully shown. ### Step 3: Test 1. Run your app. 2. Visit the desired paywall in the [dashboard](https://app.tryhelium.com/paywalls). 3. Click the QR code button, this should open a dialog with a QR code. 4. Scan it from your device camera. 5. The paywall should display from your app. > [!NOTE] > > To see the latest changes to the paywall, you may need to restart your app and scan again. (We are working on improving this.) > [!NOTE] > > Only paywalls that are configured in an active workflow can be displayed via test link. Also, workflows with experiments may display any of the paywalls in the experiment. (We are working on improving this too.) ### Explicit URL Testing Instead of scanning, you can also craft the test link manually: 1. Open Safari and navigate to: `helium-test://helium-test?trigger=YOUR_TRIGGER_NAME` . 2. Tap "Open" when prompted to open in your app. 3. The paywall for the specified trigger will be opened. # Integrate with Your 3rd Party Analytics System Source: https://docs.tryhelium.com/guides/third-party-analytics Understanding Helium's event forwarding and analytics integration. ## Configure Automatic Event Forwarding Start with [Connect analytics and MMPs](/guides/analytics-forwarding) to set up Mixpanel, Amplitude, PostHog, or Statsig and route events to your advertising tools. This page is the event and field reference. ## What events and properties are logged? All Helium events are automatically forwarded to your analytics backend. > [!NOTE] > > Helium forwards events in batches. It may take several minutes for live events to populate in your analytics provider. ### Event Names | Event Name | Description | | - | - | | `initialization_started` | SDK initialization began | | `initialization_succeeded` | SDK successfully initialized and downloaded paywalls | | `initialization_failed` | SDK failed to initialize or download paywalls | | `experience_opened` | A paywall was presented to the user | | `experience_open_failed` | A paywall failed to open | | `experience_view_rendered` | The paywall view finished rendering | | `experience_view_render_failed` | The paywall view failed to render | | `experience_skipped` | A paywall was skipped (e.g. targeting rules excluded the user) | | `experience_dismissed` | The user dismissed the paywall | | `experience_view_closed` | The paywall view was closed | | `purchase_started` | The user tapped a purchase button | | `purchase_pending` | A purchase is pending (e.g. awaiting parental approval) | | `purchase_succeeded` | A purchase completed successfully | | `purchase_failed` | A purchase failed | | `purchase_abandoned` | The user cancelled the purchase flow | | `entitlement_restored` | A previous purchase was successfully restored | | `entitlement_restore_failed` | A purchase restore attempt failed | | `user_experiment_allocated` | The user was allocated to an experiment variant | | `custom_event` | A custom analytics event fired from the paywall | ### Field Names Below is a preview of the key fields that are sent with Helium events to your analytics system. For the complete list of all fields, download the JSON file. > [card] [Download Full Field List](/files/helium-event-fields.json) > > Download a JSON file containing all event field names, types, and descriptions #### Common Event Fields | Field Name | Description | | - | - | | `helium_event_timestamp` | Timestamp when the event occurred | | `helium_event_name` | Event type name (see Event Name Mapping tab) | | `experiment_id` | Experiment unique identifier | | `experiment_chosen_variant_id` | Unique identifier of the assigned variant | | `geo_country_name` | Country name derived from IP address | | `locale_country` | Device country code | | `trigger_name` | Name of the trigger that opened the paywall | | `paywall_id` | Paywall unique identifier | | `paywall_name` | Human-readable paywall name | ## Linking & Identifying Users See the **Identifying Users** section of the SDK quickstart guides. Let Helium know the user ID of your users so forwarded analytics events will link up. If your user starts out anonymous, be sure to set the **third party analytics anonymous ID** on the Helium SDK with the anonymous/device ID from your analytics provider SDK. This will allow events from an anonymous user to link up as well. # Ways to Show a Paywall Source: https://docs.tryhelium.com/guides/ways-to-show-paywall Advanced and alternative ways to present Helium paywalls beyond the standard present method. ## Overview Most of the time you'll want to use `presentPaywall()` (or `presentUpsell()` depending on your SDK version) to show paywalls. This approach is covered in each platform's quickstart guide (see navigation menu on the left). But if you need more control over how and where paywalls appear in your app, there are a few other options. ## iOS #### Embedded View ```swift theme={null} HeliumPaywall( trigger: "onboarding" ) { paywallNotShownReason in Text("Paywall failed to show") } ``` > [!WARNING] > > The iOS SDK will attempt to handle dismissal for embedded views but may not be able to depending on where you place it. You can dismissal yourself with PaywallEventHandlers. > [accordion] Example with PaywallEventHandlers > > ```swift theme={null} > HeliumPaywall( > trigger: "post_onboarding", > eventHandlers: PaywallEventHandlers() > .onOpen { event in > print("open for trigger \(event.triggerName)") > } > .onClose { event in > print("close for trigger \(event.triggerName)") > } > .onDismissed { event in > // handle user dismissal here (i.e. navigate to another screen) > print("dismiss for trigger \(event.triggerName)") > } > .onPurchaseSucceeded { event in > print("purchase made for trigger \(event.triggerName)") > } > .onCustomPaywallAction { event in > print("Custom action: \(event.actionName) with params: \(event.params)") > } > ) { paywallNotShownReason in > Text("Paywall failed to show") > } > ``` > [accordion] Keeping customPaywallTraits current when hosting in UIKit > > `customPaywallTraits` are captured when the paywall **displays** and then stay fixed for that > presentation. In SwiftUI this is handled for you as long as the traits come from state that > re-renders the view. This is the normal way you'd pass dynamic values into a view. > > When you host `HeliumPaywall` in UIKit with a `UIHostingController`, UIKit won't refresh the view > for you. If you build the hosting controller ahead of time and update traits before showing it, > drive the view from an `ObservableObject` so the latest traits reach the paywall before display: > > ```swift theme={null} > final class PaywallTraitsStore: ObservableObject { > @Published var traits: HeliumUserTraits? > } > > struct PaywallHost: View { > @ObservedObject var store: PaywallTraitsStore > let trigger: String > var body: some View { > HeliumPaywall( > trigger: trigger, > config: PaywallPresentationConfig(customPaywallTraits: store.traits) > ) { paywallNotShownReason in > Text("Paywall failed to show") > } > } > } > > // UIKit > let store = PaywallTraitsStore() > store.traits = initialTraits > let vc = UIHostingController(rootView: PaywallHost(store: store, trigger: "onboarding")) > > // Later, before the paywall is displayed: > store.traits = freshTraits // reaches the paywall via the refreshed config > ``` > > > [!NOTE] > > > > This applies before the paywall is on screen. Once displayed, traits are locked for that > > presentation. Updating the store afterward won't change an already-shown paywall. #### SwiftUI ViewModifier Attach a paywall to any SwiftUI view using the **`.heliumPaywall`** view modifier: ```swift theme={null} struct ContentView: View { @State var isPresented: Bool = false var body: some View { VStack { Button { isPresented = true } label: { Text("Show paywall") } }.heliumPaywall( isPresented: $isPresented, trigger: "post_onboarding") { paywallNotShownReason in Text("Paywall failed to show") } } } ``` > [!NOTE] > > If you are using UIKit, you can use a UIHostingController. ## Android #### Embedded Paywall (Compose) > [!NOTE] > > Make sure to add `com.tryhelium.paywall:compose-ui:4.0.0` to your dependencies. ```kotlin theme={null} HeliumPaywall( trigger = "onboarding", onPaywallNotShown = { reason -> Text("Paywall failed to show") } ) ``` ## React Native React Native (both `expo-helium` and `@tryheliumai/paywall-sdk-react-native`) currently supports full-screen presentation via `presentUpsell()` only — embedded paywall views are not yet available. ## Flutter #### Widget Integration > [!WARNING] > > Flutter embedded widget currently only works for iOS. Android support is in the works. Embed a paywall directly in your widget tree using **`HeliumFlutter.getUpsellWidget`**: ```dart theme={null} class ExamplePageWithEmbeddedPaywall extends StatelessWidget { const ExamplePageWithEmbeddedPaywall({super.key}); @override Widget build(BuildContext context) { return Scaffold( body: HeliumPaywall( trigger: "insert-trigger-here", paywallNotShownBuilder: (context, reason) => Text("Paywall failed to show"), ), ); } } ``` > [!WARNING] > > You will have to handle your own dismissal. You can do so by passing in PaywallEventHandlers and using the `onDismissed` handler. # Android: Migrating from v0 to v4 Source: https://docs.tryhelium.com/migrations/android-0-to-4 Migration guide for Helium Android SDK v4 > [!WARNING] > > **Breaking Changes in v4:** > > * `presentUpsell()` renamed to `presentPaywall()` with new signature > * `hideUpsell()` renamed to `hidePaywall()` > * `hideAllUpsells()` renamed to `hideAllPaywalls()` > * Initialize parameters moved to `Helium.identity` and `Helium.config` namespaces > * `HeliumFallbackConfig` removed - use `Helium.config` properties instead > [!NOTE] > > **What's New:** > > * Simplified `initialize()` - just pass context and API key > * Automatic `PlayStorePaywallDelegate` setup if not explicitly configured > * Cleaner namespaced APIs: `Helium.identity`, `Helium.config` > * New `PaywallPresentationConfig` consolidates presentation options > * New `PaywallNotShownReason` for handling paywall failures ## Installation Update Update your version constraint to `4.x`: > [tab] Core (Android View System) > > ```kotlin theme={null} > // app/build.gradle.kts > dependencies { > implementation("com.tryhelium.paywall:core:4.0.0") > } > ``` > [tab] Jetpack Compose UI > > ```kotlin theme={null} > // app/build.gradle.kts > dependencies { > implementation("com.tryhelium.paywall:compose-ui:4.0.0") > } > ``` > [tab] RevenueCat > > ```kotlin theme={null} > // app/build.gradle.kts > dependencies { > implementation("com.tryhelium.paywall:revenue-cat:4.0.0") > } > ``` Then sync your Gradle files. ## Initialize Migration The biggest change in v4 is the simplified initialization. Configuration that was previously passed to `initialize()` is now set on dedicated namespaces beforehand. **v0 (many parameters):** ```kotlin theme={null} val heliumPaywallDelegate = PlayStorePaywallDelegate(this) Helium.initialize( context = this, apiKey = "...", heliumPaywallDelegate = heliumPaywallDelegate, customUserId = "user-123", customUserTraits = HeliumUserTraits( traits = mapOf("plan" to HeliumUserTraitsArgument.StringParam("free")) ), fallbackConfig = HeliumFallbackConfig.withFallbackBundle( fallbackBundleName = "fallback.json" ), environment = HeliumEnvironment.PRODUCTION, ) ``` **v4 (simplified):** ```kotlin theme={null} // Set up user identification Helium.identity.userId = "user-123" Helium.identity.setUserTraits(HeliumUserTraits( traits = mapOf("plan" to HeliumUserTraitsArgument.StringParam("free")) )) // Set up configuration (if needed) Helium.config.customFallbacksFileName = "fallback.json" // Note: PlayStorePaywallDelegate is auto-created if not set // Helium.config.heliumPaywallDelegate = PlayStorePaywallDelegate(this) // Initialize Helium.initialize( context = this, apiKey = "...", environment = HeliumEnvironment.PRODUCTION, ) ``` > [!TIP] > > Set identity and configuration values **before** calling `initialize()` for best results. > [!NOTE] > > See the [quickstart](/sdk/quickstart-android) for more details. ## presentUpsell to presentPaywall The method has been renamed and the signature has changed significantly. Parameters are now consolidated into `PaywallPresentationConfig`. ```kotlin v0 theme={null} Helium.presentUpsell( context = this, trigger = "premium", activityContext = activity, dontShowIfAlreadyEntitled = true, eventListener = myListener ) ``` ```kotlin v4 theme={null} Helium.presentPaywall( trigger = "premium", config = PaywallPresentationConfig( fromActivityContext = activity, dontShowIfAlreadyEntitled = true ), eventListener = myListener, onPaywallNotShown = { reason -> // handle paywall not shown } ) ``` ### Full Example with All Parameters **v4:** ```kotlin theme={null} Helium.presentPaywall( trigger = "premium", config = PaywallPresentationConfig( fromActivityContext = activity, // optional - SDK auto-tracks activities customPaywallTraits = HeliumUserTraits(...), dontShowIfAlreadyEntitled = true, disableSystemBackNavigation = false, presentationStyle = HeliumPresentationStyle.SLIDE_UP, fullscreen = false ), onEntitled = { // User is now entitled (purchased or restored) }, eventListener = myListener, onPaywallNotShown = { reason -> when (reason) { is PaywallNotShownReason.TargetingHoldout -> { // User is in holdout group } is PaywallNotShownReason.AlreadyEntitled -> { // User already has access } is PaywallNotShownReason.Error -> { // Handle error, check reason.unavailableReason } } } ) ``` ## Method Renames | v0 | v4 | | - | - | | `Helium.presentUpsell()` | `Helium.presentPaywall()` | | `Helium.hideUpsell()` | `Helium.hidePaywall()` | | `Helium.hideAllUpsells()` | `Helium.hideAllPaywalls()` | ## API Namespace Migration ### Helium.identity | v0 | v4 | | - | - | | `initialize(customUserId: ...)` | `Helium.identity.userId = ...` | | `initialize(customUserTraits: ...)` | `Helium.identity.setUserTraits(...)` | ### Helium.config | v0 | v4 | | - | - | | `initialize(heliumPaywallDelegate: ...)` | `Helium.config.heliumPaywallDelegate = ...` | | `initialize(fallbackConfig: ...)` | See Fallback Changes below | ## Fallback Changes v4 removes `HeliumFallbackConfig` and simplifies fallback configuration. ### What's Changed * **No more `HeliumFallbackConfig` class** - Use `Helium.config` properties directly * **No more fallback views** - Use fallback bundles exclusively * **No more per-trigger config** - Use global settings only * **Automatic detection** - SDK auto-detects `helium-fallbacks.json` in your assets ### Migration **v0:** ```kotlin theme={null} Helium.initialize( // ... other parameters fallbackConfig = HeliumFallbackConfig( fallbackBundleName = "my-fallback.json", fallbackView = myFallbackView, useLoadingState = true, loadingBudgetInMs = 5000, perTriggerLoadingConfig = mapOf(...) ) ) ``` **v4:** ```kotlin theme={null} // Option 1: Automatic (recommended) // Just add helium-fallbacks.json to your assets - SDK finds it automatically // Option 2: Custom file name Helium.config.customFallbacksFileName = "my-fallback.json" Helium.config.defaultLoadingBudgetInMs = 5000 Helium.config.defaultLoadingView = myLoadingView // optional Helium.initialize( // initialize parameters ) ``` ### Configuration Property Mapping | v0 (HeliumFallbackConfig) | v4 (Helium.config) | | - | - | | `fallbackBundleName` | `customFallbacksFileName` | | `loadingBudgetInMs` | `defaultLoadingBudgetInMs` | | `loadingView` | `defaultLoadingView` | | `useLoadingState` | Computed from `defaultLoadingBudgetInMs > 0` | | `perTriggerLoadingConfig` | Removed | | `fallbackPerTrigger` | Removed | | `fallbackView` | Removed (use fallback bundles only) | > [!NOTE] > > Download your fallbacks from the Helium dashboard. See the [Fallback Bundle Guide](/guides/fallback-bundle) for details. ## New Classes ### PaywallPresentationConfig Consolidates all paywall presentation options into a single data class: ```kotlin theme={null} data class PaywallPresentationConfig( val fromActivityContext: Activity? = null, val customPaywallTraits: HeliumUserTraits? = null, val dontShowIfAlreadyEntitled: Boolean = false, val disableSystemBackNavigation: Boolean = false, val presentationStyle: HeliumPresentationStyle = HeliumPresentationStyle.SLIDE_UP, val fullscreen: Boolean = false ) { companion object { val Default: PaywallPresentationConfig } } ``` ### PaywallNotShownReason Sealed class for handling paywall presentation failures: ```kotlin theme={null} sealed class PaywallNotShownReason { data object TargetingHoldout : PaywallNotShownReason() data object AlreadyEntitled : PaywallNotShownReason() data class Error(val unavailableReason: PaywallUnavailableReason?) : PaywallNotShownReason() } ``` ## Quick Migration Checklist Use this checklist to ensure you've covered all migration steps: * Update SDK to 4.x * Move user ID/traits to `Helium.identity.*` before `initialize()` * Move delegate to `Helium.config.*` before `initialize()` (or let SDK auto-create) * Replace `presentUpsell()` with `presentPaywall()` and update parameters * Replace `hideUpsell()` with `hidePaywall()` * Replace `hideAllUpsells()` with `hideAllPaywalls()` * Remove `HeliumFallbackConfig` usage, migrate to `Helium.config.*` properties * Set up fallback bundle (download from dashboard, add as `helium-fallbacks.json`) * Add `onPaywallNotShown` handler to `presentPaywall()` calls * Test paywall presentation and purchases ## Need Help? * Review the [Android SDK Quickstart](/sdk/quickstart-android) * Contact support via Slack or [founders@tryhelium.com](mailto:founders@tryhelium.com) # Migrating from 2.x to 3.0 Source: https://docs.tryhelium.com/migrations/ios-2-to-3 Key changes and migration guide for Helium iOS SDK v3.0 ## Summary > [!NOTE] > > React Native & Flutter: This guide applies for anyone upgrading React Native / Flutter from 0.x.x to 3.0.x. React Native and Flutter did not have a major version 1 or 2. > [!WARNING] > > **Breaking Changes in v3.0:** > > * **Minimum iOS version**: Now requires iOS 15.0+ (up from iOS 14.0) > [!NOTE] > > **What's new:** > > * Event handlers can be passed directly to `presentUpsell` > * Loading budgets for paywall downloads > * [Improved event system](/guides/helium-events) > * StoreKitDelegate used by default (iOS only) > * `customPaywallTraits` can be set when showing a paywall > > Most if not all of your 2.x Helium usages should work without change, but might be deprecated. ## Event Handlers in presentUpsell You can now pass completion handlers directly when presenting paywalls. ### Before v3 (iOS example) ```swift theme={null} Helium.shared.presentUpsell(trigger: "premium_upgrade") ``` ### v3 ```swift theme={null} Helium.shared.presentUpsell( trigger: "premium_upgrade", eventHandlers: PaywallEventHandlers() .onOpen { event in print("\(event.paywallName) via trigger \(event.triggerName)") } .onClose { event in print("\(event.paywallName) for trigger \(event.triggerName)") } .onDismissed { event in print("\(event.paywallName) for trigger \(event.triggerName)") } .onPurchaseSucceeded { event in print("\(event.paywallName) for trigger \(event.triggerName)") } ) ``` ## Loading Budget for Paywalls Before v3, if a Helium download was in progress but you wanted to show a paywall immediately (e.g., on app open), the Helium SDK would just show you a fallback paywall. In v3.0, it'll now show a loading state (by default, a shimmer view for 2 seconds) and wait for the download to complete. You can configure, turn off, or set trigger-specific loading budgets. ### How It Works ```mermaid theme={null} graph LR A[Trigger Paywall] --> B{Config Ready?} B -->|Yes| C[Show Remote Paywall] B -->|No| D[Start Loading] D --> E{Loading Budget} E -->|Time Remaining| F[Show Loading View] E -->|Budget Exceeded| G[Show Fallback] F --> H{Config Downloaded?} H -->|Yes| C H -->|No| E ``` ### Configure Loading Budgets Set different loading budgets per trigger or globally: ```swift iOS theme={null} let fallbackConfig = HeliumFallbackConfig( fallbackView: YourFallbackView(), // Global loading budget (in seconds) loadingBudget: 2.0, // Per-trigger loading budgets perTriggerLoadingConfig: [ "onboarding": TriggerLoadingConfig(loadingBudget: 4), "quick_upgrade": TriggerLoadingConfig(useLoadingState: false), ] ) Helium.shared.initialize( apiKey: "your-api-key", fallbackConfig: fallbackConfig ) ``` ```tsx React Native theme={null} const paywallLoadingConfig: HeliumPaywallLoadingConfig = { useLoadingState: true, loadingBudget: 4, perTriggerLoadingConfig: { "onboarding": { loadingBudget: 5, }, "trial": { useLoadingState: false, } }, }; initialize({ apiKey: "helium-api-key", purchaseConfig: createRevenueCatPurchaseConfig( {apiKey: 'rc-api-key'} ), onHeliumPaywallEvent: (event: HeliumPaywallEvent) => { console.log('Helium Paywall Event:', event); }, fallbackBundle: require('./assets/fetched.json'), paywallLoadingConfig: paywallLoadingConfig, // << pass to initialize }); ``` ```dart Flutter theme={null} final paywallLoadingConfig = HeliumPaywallLoadingConfig( loadingBudget: 5, perTriggerLoadingConfig: { "onboarding": TriggerLoadingConfig(useLoadingState: false), "from_menu": TriggerLoadingConfig(useLoadingState: true, loadingBudget: 2), } ); HeliumFlutter().initialize( // [Required] You'll get this from Helium founders during setup! apiKey: "", paywallLoadingConfig: paywallLoadingConfig, ); ``` ### Custom Loading Views (iOS only) Provide custom loading views during the budget period: ```swift theme={null} let fallbackConfig = HeliumFallbackConfig( fallbackView: YourFallbackView(), loadingView: { progress in VStack { ProgressView("Loading premium options...") Text("\(Int(progress * 100))% complete") } } ) ``` ### Disable Loading Budget To show fallback immediately without waiting: ```swift theme={null} let fallbackConfig = HeliumFallbackConfig( fallbackView: YourFallbackView(), useLoadingState: false // Immediate fallback ) ``` ## Required Fallbacks (iOS only) Fallbacks are mandatory. You must either provide a `fallbackConfig` (v3.0 way) or a `fallbackPaywall` (old way). The SDK will fail to initialize without some type of fallback configuration. ### Before (v2.x) ```swift theme={null} Helium.shared.initialize( apiKey: "your-api-key", heliumPaywallDelegate: delegate, fallbackPaywall: YourFallbackView() ) ``` ### After (v3.0) ```swift theme={null} let fallbackConfig = HeliumFallbackConfig( // Required: Basic fallback view fallbackView: Text("Premium Features Available"), // Recommended: Fallback bundle fallbackBundle: Bundle.main.url( forResource: "fallback-bundle", withExtension: "json" ) ) Helium.shared.initialize( apiKey: "your-api-key", fallbackConfig: fallbackConfig ) ``` ### Per-Trigger Fallbacks Configure different fallbacks for different triggers: ```swift theme={null} let fallbackConfig = HeliumFallbackConfig( fallbackView: DefaultFallbackView(), fallbackPerTrigger: [ "onboarding": OnboardingFallbackView(), "premium_feature": PremiumFeatureFallbackView(), "trial_expiry": TrialExpiryFallbackView() ] ) ``` ## Event System Changes The event system now uses protocol-based events with better type safety and IDE support. ### Key Event Changes From Before v3 #### Name Changes * `paywallTemplateName` → `paywallName` * `productKey` → `productId` * All `subscription*` events → `purchase*` events (e.g., `subscriptionSucceeded` → `PurchaseSucceededEvent`) * `ctaPressed` event → `PaywallButtonPressedEvent` * `error` is now `Error` type instead of `String` on `PurchaseFailedEvent` > [!NOTE] > > React Native & Flutter had several changes to event `type`: > > * ctaPressed → paywallButtonPressed > * offerSelected → productSelected > * subscriptionPressed → purchasePressed > * subscriptionCancelled → purchaseCancelled > * subscriptionSucceeded → purchaseSucceeded > * subscriptionFailed → purchaseFailed > * subscriptionRestored → purchaseRestored > * subscriptionRestoreFailed → purchaseRestoreFailed > * subscriptionPending → purchasePending #### Removed * `configId` removed from download success events ### New Delegate Method (iOS only) #### Before v3 `onHeliumPaywallEvent(event:)` (deprecated but still works) ```swift theme={null} func onHeliumPaywallEvent(event: HeliumPaywallEvent) { switch event { case .paywallOpen(let trigger, let paywallTemplateName, _): analytics.track("paywall_open", trigger: trigger) case .subscriptionSucceeded(let productKey, let trigger, _): analytics.track("purchase", product: productKey) case .subscriptionFailed(let productKey, _, _, let errorString): print("Purchase failed: \(errorString ?? "unknown")") default: break } } ``` #### v3 `onPaywallEvent(_:)` (recommended) ```swift theme={null} func onPaywallEvent(_ event: PaywallEvent) { switch event { case let openEvent as PaywallOpenEvent: analytics.track("paywall_open", trigger: openEvent.triggerName, paywall: openEvent.paywallName ) case let purchaseEvent as PurchaseSucceededEvent: analytics.track("purchase", product: purchaseEvent.productId ) case let failedEvent as PurchaseFailedEvent: if let error = failedEvent.error { print("Purchase failed: \(error.localizedDescription)") } default: break } } ``` ## StoreKit Delegate by Default (iOS only) If no delegate is provided, v3.0 uses StoreKitDelegate automatically. ### Before (v2.x) ```swift theme={null} Helium.shared.initialize( apiKey: "your-api-key", heliumPaywallDelegate: StoreKitDelegate(), // Required fallbackPaywall: fallbackView ) ``` ### After (v3.0) ```swift theme={null} Helium.shared.initialize( apiKey: "your-api-key", fallbackConfig: fallbackConfig // No delegate needed - StoreKitDelegate is default ) ``` ## Custom Paywall Traits You can now pass custom paywall traits when displaying a paywall, replacing the deprecated `HeliumPaywallDelegate.getCustomVariableValues` method. ```swift theme={null} Helium.shared.presentUpsell( trigger: "premium_upgrade", customPaywallTraits: [ "feature_attempted": "export_pdf", "usage_this_session": 15, "current_screen": "document_editor" ] ) ``` ## Minimum iOS Version Update your app's minimum deployment target to iOS 15.0 or later. > [tab] iOS > > 1. Select your project in Xcode > 2. Go to your app target > 3. Set "Minimum Deployments" to iOS 15.0 > [tab] React Native > > If using Expo: > > 1. Make sure the `expo-build-properties` package is installed (should be installed by default) > 2. Update your app config (app.json, app.config.js, app.config.ts): > > ```json theme={null} > [ > "expo-build-properties", > { > ios: { > deploymentTarget: "15.0", // or higher > }, > }, > ], > ``` > > If not using Expo, adjust in your Xcode project directly. > [tab] Flutter > > [Flutter minimum](https://docs.tryhelium.com/sdk/quickstart-flutter#ios-settings) was already iOS 15. ## Need Help? * Review the [iOS SDK Quickstart](/sdk/quickstart-ios) * See the [Complete Example App](https://github.com/cloudcaptainai/example-helium-swift) on GitHub * Contact support via Slack or [founders@tryhelium.com](mailto:founders@tryhelium.com) # iOS: Migrating from v3 to v4 Source: https://docs.tryhelium.com/migrations/ios-3-to-4 Migration guide for Helium iOS SDK v4 > [!WARNING] > > **Breaking Changes in v4:** > > * `presentUpsell()` renamed to `presentPaywall()` with required `onPaywallNotShown` handler > * Initialize parameters moved to `Helium.identify` and `Helium.config` namespaces > * Fallback views removed - use fallback bundles only > [!NOTE] > > **What's New:** > > * Simplified `initialize()` - just pass your API key > * Automatic fallback bundle detection (`helium-fallbacks.json`) > * Cleaner namespaced APIs: `Helium.identify`, `Helium.config`, `Helium.experiments`, `Helium.entitlements` > * New `HeliumPaywall` SwiftUI component for embedded paywalls > * **HeliumRevenueCat** is now a separate SPM package (CocoaPods unchanged) ## Installation Update Update your version constraint to `~> 4.0`: > [tab] Swift Package Manager > > Update the **Dependency Rule** in Xcode to allow 4.x versions, or remove and re-add the package with the new version constraint. > > > [!WARNING] > > > > **RevenueCat users:** HeliumRevenueCat is now a separate SPM package. After updating to v4, you may see a build error: > > > > ``` > > Product 'HeliumRevenueCat' not found in package 'helium-swift' > > ``` > > > > To fix this: > > > > 1. In your target's **Frameworks, Libraries, and Embedded Content**, remove the broken **HeliumRevenueCat** reference > > 2. Go to **Package Dependencies** and add the new package: > > ``` > > https://github.com/cloudcaptainai/helium-swift-revenuecat.git > > ``` > > 3. Add the **HeliumRevenueCat** product from the new package to your app's main target > [tab] Cocoapods > > Update your Podfile: > > ```ruby theme={null} > # Core only > pod 'Helium', '~> 4.0' > > # Or with RevenueCat > pod 'Helium/RevenueCat', '~> 4.0' > ``` > > Then run: > > ```bash theme={null} > pod install > ``` ## Initialize Migration The biggest change in v4 is the simplified initialization. Configuration that was previously passed to `initialize()` is now set on dedicated namespaces beforehand. **v3 (many parameters):** ```swift theme={null} // Deprecated v3 initialize Helium.shared.initialize( apiKey: "...", heliumPaywallDelegate: RevenueCatDelegate(), customUserId: "user-123", customUserTraits: HeliumUserTraits(["plan": "free"]), fallbackConfig: .withFallbackBundle(bundleURL) ) ``` **v4 (simplified):** ```swift theme={null} // Set up user identification Helium.identify.userId = "user-123" Helium.identify.setUserTraits(HeliumUserTraits(["plan": "free"])) // If using RevenueCat Helium.identify.revenueCatAppUserId = Purchases.shared.appUserID // Set up advanced configuration (if needed) Helium.config.customFallbacksURL = Bundle.main.url( forResource: "fallback-bundle-2026-01-25", withExtension: "json" ) Helium.config.purchaseDelegate = RevenueCatDelegate() // Initialize with just API key Helium.shared.initialize(apiKey: "...") ``` > [!TIP] > > Set identity and configuration values **before** calling `initialize()` for best results. > [!NOTE] > > See the [quickstart](/sdk/quickstart-ios) for more details. ## presentUpsell to presentPaywall The method has been renamed and now requires an `onPaywallNotShown` handler. ```swift v3 theme={null} Helium.shared.presentUpsell(trigger: "premium") ``` ```swift v4 theme={null} Helium.shared.presentPaywall(trigger: "premium") { notShownReason in // handle paywall not shown } ``` ### Full Example with All Parameters **v4:** ```swift theme={null} Helium.shared.presentPaywall( trigger: "premium", config: PaywallPresentationConfig( presentFromViewController: viewController, customPaywallTraits: ["source": "settings"], dontShowIfAlreadyEntitled: true, loadingBudget: nil, // use default ), eventHandlers: PaywallEventHandlers() .onPurchaseSucceeded { event in print("Purchased!") }, onEntitled: { // User is now entitled (purchased or restored) } ) { paywallNotShownReason in switch paywallNotShownReason { case .targetingHoldout: break case .alreadyEntitled: // User already has access break default: // Handle rare failure cases break } } ``` ## API Namespace Migration ### Helium.identify | v3 | v4 | | - | - | | `initialize(customUserId:)` | `Helium.identify.userId = ...` | | `overrideUserId()` | `Helium.identify.userId = ...` | | `getHeliumUserId()` | `Helium.identify.userId` | | `setAppAttributionToken()` | `Helium.identify.appAccountToken = ...` | | `setRevenueCatAppUserId()` | `Helium.identify.revenueCatAppUserId = ...` | ### Helium.config | v3 | v4 | | - | - | | `initialize(heliumPaywallDelegate:)` | `Helium.config.purchaseDelegate = ...` | | `setLightDarkModeOverride()` | `Helium.config.lightDarkModeOverride = ...` | | `Helium.restorePurchaseConfig` | `Helium.config.restorePurchasesDialog` | ### Helium.experiments | v3 | v4 | | - | - | | `getExperimentInfoForTrigger()` | `Helium.experiments.infoForTrigger()` | | `enrolledExperiments()` | `Helium.experiments.enrolled()` | | `allExperiments()` | `Helium.experiments.all()` | ### Helium.entitlements | v3 | v4 | | - | - | | `hasAnyEntitlement()` | `Helium.entitlements.hasAny()` | | `hasAnyActiveSubscription()` | `Helium.entitlements.hasAnyActiveSubscription()` | | `hasEntitlementForPaywall()` | `Helium.entitlements.hasForPaywall()` | | `hasActiveEntitlementFor()` | `Helium.entitlements.hasActiveFor()` | | `purchasedProductIds()` | `Helium.entitlements.purchasedProductIds()` | | `activeSubscriptions()` | `Helium.entitlements.activeSubscriptions()` | ## Fallback Changes v4 removes fallback views and simplifies fallback configuration. ### What's Changed * **No more fallback views** - Use fallback bundles exclusively * **Automatic detection** - SDK auto-detects `helium-fallbacks.json` in your main bundle * **Optional override** - Use `Helium.config.customFallbacksURL` if needed ### Migration **v3:** ```swift theme={null} let fallbackConfig = HeliumFallbackConfig( fallbackView: YourFallbackView(), fallbackBundle: Bundle.main.url( forResource: "fallback-bundle", withExtension: "json" ) ) Helium.shared.initialize( apiKey: "...", fallbackConfig: fallbackConfig ) ``` **v4:** ```swift theme={null} // Option 1: Automatic (recommended) // Just add helium-fallbacks.json to your bundle - SDK finds it automatically // Option 2: Custom location Helium.config.customFallbacksURL = Bundle.main.url( forResource: "my-fallbacks", withExtension: "json" ) Helium.shared.initialize(apiKey: "...") ``` > [!NOTE] > > Download your fallbacks from the Helium dashboard. See the [Fallback Bundle Guide](/guides/fallback-bundle) for details. ## Embedded Paywall Views The SwiftUI view for embedding paywalls has been replaced. ```swift v3 (deprecated) theme={null} let paywallView = Helium.shared.upsellViewForTrigger("premium") ``` ```swift v4 theme={null} HeliumPaywall( trigger: "premium", onPaywallNotShown: { reason in // Handle paywall not shown } ) ``` > [!NOTE] > > See [ways to show a paywall](/guides/ways-to-show-paywall) for more information. ## Removed APIs The following APIs have been removed in v4: | Removed API | Replacement | | - | - | | `getHeliumExperimentInfo()` (map version) | `Helium.experiments.all()` | | `HeliumFallbackConfig` class | Use `Helium.config.customFallbacksURL` | | All `fallback*` parameters from initialize | Add `helium-fallbacks.json` to bundle | | `upsellViewForTrigger()` | `HeliumPaywall` component | ## Quick Migration Checklist Use this checklist to ensure you've covered all migration steps: * Update SDK to 4.x (`~> 4.0`) * Move user ID/traits to `Helium.identify.*` before `initialize()` * Move delegate/config to `Helium.config.*` before `initialize()` * Replace `presentUpsell()` with `presentPaywall()` and add required handler * Set up fallback bundle (download from dashboard, add as `helium-fallbacks.json`) * Update experiment calls to `Helium.experiments.*` * Update entitlement calls to `Helium.entitlements.*` * Replace `upsellViewForTrigger()` with `HeliumPaywall` component * Test paywall presentation and purchases ## Need Help? * Review the [iOS SDK Quickstart](/sdk/quickstart-ios) * Contact support via Slack or [founders@tryhelium.com](mailto:founders@tryhelium.com) # Helium SDK Source: https://docs.tryhelium.com/sdk/overview What the Helium mobile SDK does, which platforms it supports, and where to start for iOS, Android, React Native and Flutter. The Helium SDK fetches your paywalls when the app launches, presents the right one when your code fires a trigger, and reports purchases and paywall events back to Helium. Paywall design, targeting and experiments live in the [dashboard](https://app.tryhelium.com), so you ship the SDK once and change paywalls without app updates. ## Platforms > [card] [iOS](/sdk/quickstart-ios) > > Swift, iOS 15+. Swift Package Manager or CocoaPods. > [card] [Android](/sdk/quickstart-android) > > Kotlin, Gradle. > [card] [React Native](/sdk/quickstart-react-native) > > npm package wrapping the native SDKs. > [card] [Flutter](/sdk/quickstart-flutter) > > pub.dev package wrapping the native SDKs. ## What every integration does 1. **Initialize** Helium on app launch with your API key and a delegate for purchases. 2. **Present** a paywall for a trigger name at the point in your app where the paywall should appear. 3. **Ship fallbacks** so a paywall shows even if the device is offline on first launch. See [Fallback paywalls](/guides/fallback-bundle). 4. **Report revenue** by connecting your store or RevenueCat webhooks. See [Revenue reporting](/guides/revenue-reporting). The quickstart for each platform walks through all four steps with the exact method names for that platform. ## Beyond the quickstart * [Ways to show a paywall](/guides/ways-to-show-paywall): embedded, programmatic and deep-link presentation. * [Paywall traits](/guides/paywall-traits): pass values into a paywall at presentation time. * [Custom events](/guides/custom-events): react in your app to actions taken inside a paywall. * [Helium events](/guides/helium-events): the full list of events the SDK emits. * [Migrations](/migrations/ios-3-to-4): upgrade guides for major SDK versions. # SDK Quickstart (Android) Source: https://docs.tryhelium.com/sdk/quickstart-android Integrate Helium into your Android app > [!TIP] > > To get a better understanding of how paywalls are served, visit [here](/guides/how-does-helium-work). > [!NOTE] > > Migrating from v0? View [the migration guide](/migrations/android-0-to-4). # Present a Paywall ### Install the SDK Add the Helium SDK to your project using Gradle. #### Requirements * **Kotlin Version**: 2.0.0 or higher * **Java Version**: 8 or higher * **Minimum Android SDK**: 23 or higher * **Compile Android SDK**: 35 or higher #### 1. Add repositories to your `settings.gradle.kts` file: Ensure you have `mavenCentral()` and `google()` in your repositories blocks. ```kotlin theme={null} // settings.gradle.kts pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() // You might have other repositories here } } ``` > [!NOTE] > > If you don't have a `dependencyResolutionManagement` block, ensure `google()` and `mavenCentral()` are present in your `pluginManagement { repositories { ... } }` block. #### 2. Add the dependency to your module-level `build.gradle.kts` file (e.g., `app/build.gradle.kts`): ```kotlin theme={null} // app/build.gradle.kts dependencies { implementation("com.tryhelium.paywall:core:4.0.0") } ``` ### Initialize Helium > [!TIP] > > Find your API key [here](https://app.tryhelium.com/profile). If you do not have a Helium account set up yet, you can still integrate but will not be able to show a real paywall. Initialize the Helium SDK as early as possible in your app's lifecycle. ```kotlin theme={null} Helium.initialize( context = this, apiKey = "YOUR_API_KEY", environment = HeliumEnvironment.PRODUCTION, ) ``` > [!NOTE] > > The supplied environment can be SANDBOX or PRODUCTION. If not sure, use PRODUCTION because Helium will automatically treat debug builds as SANDBOX. Choose the appropriate location based on your app's architecture: > [tab] Application > > ```kotlin theme={null} > class MyApplication : Application() { > override fun onCreate() { > super.onCreate() > //*** Add this: > configureHelium() > } > > //*** And this: > private fun configureHelium() { > Helium.initialize( > context = this, > apiKey = "YOUR_API_KEY", > environment = HeliumEnvironment.PRODUCTION, > ) > } > } > ``` > [tab] Activity > > ```kotlin theme={null} > class MainActivity : AppCompatActivity() { > override fun onCreate(savedInstanceState: Bundle?) { > super.onCreate(savedInstanceState) > //*** Add this: > configureHelium() > } > > //*** And this: > private fun configureHelium() { > Helium.initialize( > context = this, > apiKey = "YOUR_API_KEY", > environment = HeliumEnvironment.PRODUCTION, > ) > } > } > ``` And add necessary imports: ```kotlin theme={null} import com.tryhelium.paywall.core.Helium ``` ### Show Your First Paywall 🎉 > [!TIP] > > Set up a trigger and workflow in the [dashboard](https://app.tryhelium.com/workflows) to show your desired paywall. Create unique triggers for each location a paywall can show in your app! This provides more flexibility with paywall variation and experiments, allowing you to take full advantage of Helium. Call `presentPaywall` wherever you want to show a full-screen paywall: ```kotlin theme={null} Helium.presentPaywall( trigger = "premium", onPaywallNotShown = { reason -> // Handle any scenario where the paywall does not show } ) ``` **Helium.presentPaywall** `method` **parameters** **trigger** `String` *required* The trigger name configured in the Helium dashboard. **config** `PaywallPresentationConfig?` *(Optional)* Configuration for this paywall presentation. ```kotlin theme={null} data class PaywallPresentationConfig( // Activity to present from. SDK auto-tracks if not provided. val fromActivityContext: Activity? = null, // Custom traits to send to the paywall val customPaywallTraits: HeliumUserTraits? = null, // Don't show paywall if user is entitled to a product in paywall. // In most cases the default of false is desired -- see "Checking // Subscription Status & Entitlements" below before enabling this. val dontShowIfAlreadyEntitled: Boolean = false, // Disable system back button closing the paywall val disableSystemBackNavigation: Boolean = false, // How the paywall animates in val presentationStyle: HeliumPresentationStyle = HeliumPresentationStyle.SLIDE_UP, // Show in fullscreen "immersive" mode which will hide system status bars. val fullscreen: Boolean = false ) ``` **onEntitled** `(() -\> Unit)?` *(Optional)* A handler for when user is entitled to a product in the paywall, via purchase or existing entitlement. **eventListener** `HeliumEventListener?` *(Optional)* Event listener for paywall lifecycle events. **onPaywallNotShown** `((PaywallNotShownReason) -\> Unit)?` *(Optional but highly recommended)* Handle any scenario where the paywall does not show. If user is already entitled and `config.dontShowIfAlreadyEntitled` is true, `onPaywallNotShown(AlreadyEntitled)` will be called only if `onEntitled` is not provided. You should now be able to see Helium paywalls in your app! Well done! 🎉 > [!NOTE] > > Looking for alternative presentation methods? Check out the guide on [Ways to Show a Paywall](/guides/ways-to-show-paywall). # Recommended Setup Here are some common additional steps that you may want to consider. ### Identifying Users Identifying users is optional but can help with targeting and when forwarding events to external analytics platforms. If you are not sure, you probably do not need to identify your users. > [!TIP] > > Identify users as early as you can to maximize consistency in metrics and targeting. Ideally right before you call `Helium.initialize`! Set a custom user ID: ```kotlin theme={null} Helium.identity.userId = "custom-user-id" ``` Set custom user traits for targeting and analytics visibility: ```kotlin theme={null} Helium.identity.setUserTraits(HeliumUserTraits( traits = mapOf( "hasOnboarded" to HeliumUserTraitsArgument.BoolParam(true), "accountAge" to HeliumUserTraitsArgument.IntParam(30) ) )) // or Helium.identity.addUserTraits() if you don't want to clear existing traits ``` ### Helium Events Helium dispatches various events during paywall presentation and purchase flow. You can optionally handle these events in your mobile app. You can also configure Helium to forward them to your [existing analytics provider](/guides/third-party-analytics). #### PaywallEventHandlers You can create an instance of `PaywallEventHandlers` and provide lambdas for the events you are interested in. The available handlers are: * `onOpen`: Called when a paywall is displayed to the user. * `onClose`: Called when a paywall is closed for any reason. * `onDismissed`: Called when the user explicitly dismisses a paywall without purchasing. * `onPurchaseSucceeded`: Called when a purchase completes successfully. * `onCustomPaywallAction`: Called when a custom action is triggered from the paywall. * `onAnyEvent`: Called for any of the above events. To register your handlers, use `Helium.shared.addPaywallEventListener`. You can either tie the listener to a lifecycle (recommended) or manage it manually. **Lifecycle-Aware (Recommended)** Pass a `LifecycleOwner` (like an `Activity` or `Fragment`) to have the listener automatically removed when the lifecycle is destroyed. ```kotlin theme={null} class MyActivity : AppCompatActivity() { private val paywallEventHandlers = PaywallEventHandlers( onOpen = { event -> print("Paywall opened: ${event.paywallName}") }, onClose = { event -> print("Paywall closed: ${event.paywallName}") } // ... other event handlers ) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Add the listener once, it will be cleaned up automatically Helium.shared.addPaywallEventListener(this, paywallEventHandlers) } } ``` > [!WARNING] > > If you don't provide a `LifecycleOwner`, you are responsible for removing the listener with `removeHeliumEventListener()` to prevent memory leaks. #### Global Event Listener For a more centralized approach, your class can implement the `HeliumEventListener` interface and handle all events in a single `onHeliumEvent` method. ```kotlin theme={null} import com.tryhelium.paywall.core.event.* class MyActivity : AppCompatActivity(), HeliumEventListener { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Add the listener once, it will be cleaned up automatically Helium.shared.addPaywallEventListener(this, this) } override fun onHeliumEvent(event: HeliumEvent) { when (event) { is PaywallOpen -> { // Handle paywall open } is PaywallClose -> { // Handle paywall close } // ... handle other event types } } } ``` ### Fallback Paywalls It is **highly recommended** that you set up "fallbacks" to handle the rare case when a paywall fails to display. Please follow [this guide](/guides/fallback-bundle) to do so. > [!TIP] > > Do this *after* you have a paywall created that you want to use in production. ### Checking Subscription Status & Entitlements Helium checks entitlements directly through Google Play Billing and provides helper methods to make this easier. Consider checking entitlements to gate premium features. > [!NOTE] > > If you have a backend server that manages user entitlements, you may have no use for these helpers. > [accordion] All Entitlement Helper Methods > > Accessed from `Helium.entitlements`: > > `hasAnyEntitlement()` Checks if the user has purchased any subscription or non-consumable product. > > `hasAnyActiveSubscription()` Checks if the user has any active subscription. > > `hasEntitlementForPaywall(trigger: String)` Checks if the user has entitlements for any product in a specific paywall. Returns `null` if paywall configuration hasn't been downloaded yet. If you want to check entitlement status before presenting a paywall, here are a couple of ways to do so. > [!NOTE] > > For paywalls that are user-initiated (e.g. "Upgrade to Premium") and onboarding paywalls, checking entitled status is not recommended. Apps usually want to consistently show a paywall for these locations, and users can still "Restore Purchases" as needed. ```kotlin Use dontShowIfAlreadyEntitled with presentPaywall theme={null} Helium.presentPaywall( trigger = "my_paywall_trigger", config = PaywallPresentationConfig( dontShowIfAlreadyEntitled = true, ), onPaywallNotShown = { paywallNotShownReason -> // handle paywall not shown } ) ``` ```kotlin Check before showing paywall theme={null} val hasActiveSubscription = Helium.entitlements.hasAnyActiveSubscription() if (hasActiveSubscription) { // access premium content } else { // show paywall } ``` # Advanced ### Consumables > [!NOTE] > > This only applies if using the default `PlayStorePaywallDelegate` for purchase handling. If you are using `RevenueCatPaywallDelegate`, configure RevenueCat to consume appropriate purchases. If you use a custom `HeliumPaywallDelegate`, you are responsible for consuming purchases. If your app sells consumable products (e.g., coins, credits, or tokens) and you want Helium to consume purchases for these products, relay these product IDs to Helium: ```kotlin theme={null} Helium.config.consumableIds = setOf("coins_100", "gems_50") ``` ### RevenueCat > [!NOTE] > > By default, Helium will handle purchases for you! This section is typically for users who already use RevenueCat in their app. Helium integrates seamlessly with RevenueCat so you can continue to let RevenueCat handle your purchases and entitlements. #### Install HeliumRevenueCat Add the RevenueCat dependency to your module-level `build.gradle.kts`: ```kotlin theme={null} // app/build.gradle.kts dependencies { implementation("com.tryhelium.paywall:core:4.0.0") implementation("com.tryhelium.paywall:revenue-cat:4.0.0") } ``` #### Configure Helium to use RevenueCat for Purchases Simply use Helium's pre-built `RevenueCatPaywallDelegate`: ```kotlin theme={null} Helium.config.heliumPaywallDelegate = RevenueCatPaywallDelegate() ``` > [!WARNING] > > Make sure to initialize RevenueCat *before* creating the RevenueCatPaywallDelegate! > [!TIP] > > It is best to do this configuration *before* you call `Helium.initialize`. #### RevenueCat appUserID If you ever [change the appUserID](https://www.revenuecat.com/docs/customers/identifying-customers#logging-in-after-configuration) of a user, keep Helium in sync with: ```kotlin theme={null} Helium.identify.revenueCatAppUserId = Purchases.sharedInstance.appUserID ``` ### Custom Purchase Handling > [!NOTE] > > By default, Helium will handle purchases for you! This section is for those who want to implement custom purchase logic. > [!TIP] > > Want to add some custom behavior but still use the built-in purchase logic? Just subclass `PlayStorePaywallDelegate` or `RevenueCatPaywallDelegate`! (Be sure to make a `super` call for any overridden methods.) You can create a custom delegate and implement your own purchase logic. The `HeliumPaywallDelegate` is defined as follows: ```kotlin theme={null} interface HeliumPaywallDelegate { suspend fun makePurchase( productDetails: ProductDetails, basePlanId: String?, offerId: String?, ): HeliumPaywallTransactionStatus suspend fun restorePurchases(): Boolean fun onHeliumEvent(event: HeliumEvent) } ``` ### Additional Features > [!NOTE] > > For the full public API and detailed parameter documentation, see the inline docstrings in the SDK source. Import Helium in your project and use your IDE's autocomplete or jump-to-definition to explore all available methods and types. > [accordion] In-App Paywall Links > > By default, web links (`http`/`https`) opened via a paywall's navigate action open in the external browser. To open them in-app in a Chrome Custom Tab over the paywall instead: > > ```kotlin theme={null} > Helium.config.openPaywallLinksInApp = true > ``` > > Non-web links (e.g. `mailto:`, `tel:`) and direct HTML anchor taps always open externally. > [accordion] Checking Download Status > > > [!TIP] > > > > In most cases there is no need to check download status. Helium will display a loading indication if a paywall is presented before download has completed. > > The `downloadStatus` is a Kotlin `Flow` that emits `HeliumConfigStatus` states. The possible states are: > > * `HeliumConfigStatus.NotYetDownloaded`: The initial state before the download has started. > * `HeliumConfigStatus.Downloading`: Indicates that the paywall configuration is currently being downloaded. > * `HeliumConfigStatus.DownloadFailure`: Indicates that the paywall configuration download has failed. > * `HeliumConfigStatus.DownloadSuccess`: Indicates that the paywall configuration has been successfully downloaded. > > Here's how you can observe the `downloadStatus` flow in your Activity or Fragment: > > ```kotlin theme={null} > // In your Activity or Fragment > lifecycleScope.launch { > Helium.shared.downloadStatus.collect { status -> > when (status) { > is HeliumConfigStatus.NotYetDownloaded -> { > // Handle not yet downloaded state > } > is HeliumConfigStatus.Downloading -> { > // Handle downloading state > } > is HeliumConfigStatus.DownloadFailure -> { > // Handle download failure > } > is HeliumConfigStatus.DownloadSuccess -> { > // Handle download success > } > } > } > } > ``` > [accordion] Hiding Paywalls Programmatically > > You can programmatically hide paywalls using: > > ```kotlin theme={null} > // Hide the current paywall > Helium.hidePaywall() > > // Hide all currently displayed paywalls > Helium.hideAllPaywalls() > ``` > [accordion] Reset Helium > > Reset Helium entirely so you can call initialize again, for example after changing user traits that can affect the paywalls a user might see via targeting. > > ```kotlin theme={null} > Helium.resetHelium() > ``` # SDK Quickstart (Android) - v0 Source: https://docs.tryhelium.com/sdk/quickstart-android-v0 Legacy quickstart for Helium Android SDK v0. New integrations should use the current Android quickstart; v0 users should follow the v0 to v4 migration guide. > [!WARNING] > > This guide is for **v0.x** of the Android SDK. For the latest version, see the [v4 quickstart](/sdk/quickstart-android). ## Background Get set up with the Helium SDK for Android. Reach out over your Helium slack channel or email [founders@tryhelium.com](mailto:founders@tryhelium.com) for any questions. ## Installation Add the Helium SDK to your project using Gradle. ### Requirements * **Kotlin Version**: 2.0.0 or higher * **Java Version**: 8 or higher * **Minimum Android SDK**: 23 or higher * **Compile Android SDK**: 35 or higher #### 1. Add repositories to your `settings.gradle.kts` file: Ensure you have `mavenCentral()` and `google()` in your repositories blocks. ```kotlin theme={null} // settings.gradle.kts pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() // You might have other repositories here } } ``` > [!NOTE] > > If you don't have a `dependencyResolutionManagement` block, ensure `google()` and `mavenCentral()` are present in your `pluginManagement { repositories { ... } }` block. #### 2. Add the dependencies to your module-level `build.gradle.kts` file (e.g., `app/build.gradle.kts`): > [tab] Core (Android View System) > > ```kotlin theme={null} > // app/build.gradle.kts > > dependencies { > // Choose one of the UI modules: > implementation("com.tryhelium.paywall:core:0.1.11") > // Other app dependencies > } > ``` > [tab] Jetpack Compose UI > > ```kotlin theme={null} > // app/build.gradle.kts > > dependencies { > // Choose one of the UI modules: > implementation("com.tryhelium.paywall:compose-ui:0.1.11") > // Other app dependencies > } > ``` > [tab] RevenueCat > > ```kotlin theme={null} > // app/build.gradle.kts > > dependencies { > // If you're using RevenueCat, add this dependency: > implementation("com.tryhelium.paywall:revenue-cat:0.1.11") > // Other app dependencies > } > ``` ## Initialize Helium You need to initialize Helium before you can present a paywall. The best place to do this is in your `MainActivity`'s `onCreate()` method. ```kotlin theme={null} // In your MainActivity class's onCreate() method import com.tryhelium.paywall.core.HeliumEnvironment class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val heliumPaywallDelegate = PlayStorePaywallDelegate(this) // Or your custom delegate Helium.initialize( context = this, apiKey = "YOUR_API_KEY", heliumPaywallDelegate = heliumPaywallDelegate, environment = HeliumEnvironment.SANDBOX // Or HeliumEnvironment.PRODUCTION ) } } ``` **Helium.initialize** `method` **parameters** **context** `Context` *required* The Android application context. Use `this` in an Activity or `applicationContext` for the application context. **apiKey** `String` *required* You can create or retrieve your api key from [Account Settings](https://app.tryhelium.com/profile). **heliumPaywallDelegate** `HeliumPaywallDelegate` *required* Delegate to handle paywall events and callbacks (see HeliumPaywallDelegate section) **environment** `HeliumEnvironment` *required* The environment to use: `HeliumEnvironment.SANDBOX` for development and testing, or `HeliumEnvironment.PRODUCTION` for your live app. Note that Helium automatically forces SANDBOX for debug builds. **customUserId** `String?` *(Optional)* If set, a custom user id to use instead of Helium's. We'll use this id when forwarding to third party analytics services, so this can be used for attribution (e.g. an amplitude user id, or a custom user id from your own analytics service) **customUserTraits** `HeliumUserTraits?` *(Optional)* Pass in custom user traits to be used for targeting, personalization, and dynamic content. It can be created with a map where keys are strings and values are wrapped in the appropriate `HeliumUserTraitsArgument` type. ```kotlin theme={null} val customUserTraits = HeliumUserTraits( traits = mapOf( "testTrait" to HeliumUserTraitsArgument.IntParam(1), "account_age_in_days" to HeliumUserTraitsArgument.StringParam("20") ) ) ``` **fallbackConfig** `HeliumFallbackConfig?` *(Optional)* Fallback configuration with either a view or bundle. See the Fallbacks and Loading Budgets section for details. **customApiEndpoint** `String?` *(Optional)* A custom API endpoint URL. Only use this if directed by Helium support. **logger** `Logger?` *(Optional)* The logger to use for Helium SDK logging. Defaults to standard output. > [accordion] Checking Download Status > > > [!NOTE] > > > > In most cases there is no need to check download status. Helium will display a loading indication if a paywall is presented before download has completed. > > The `downloadStatus` is a Kotlin `Flow` that emits `HeliumConfigStatus` states. The possible states are: > > * `HeliumConfigStatus.NotYetDownloaded`: The initial state before the download has started. > * `HeliumConfigStatus.Downloading`: Indicates that the paywall configuration is currently being downloaded. > * `HeliumConfigStatus.DownloadFailure`: Indicates that the paywall configuration download has failed. > * `HeliumConfigStatus.DownloadSuccess`: Indicates that the paywall configuration has been successfully downloaded. > > Here's how you can observe the `downloadStatus` flow in your Activity or Fragment: > > ```kotlin theme={null} > // In your Activity or Fragment > lifecycleScope.launch { > Helium.shared.downloadStatus.collect { status -> > when (status) { > is HeliumConfigStatus.NotYetDownloaded -> { > // Handle not yet downloaded state > } > is HeliumConfigStatus.Downloading -> { > // Handle downloading state > } > is HeliumConfigStatus.DownloadFailure -> { > // Handle download failure > } > is HeliumConfigStatus.DownloadSuccess -> { > // Handle download success > } > } > } > } > ``` ## HeliumPaywallDelegate You can provide an implementation of the `HeliumPaywallDelegate` or use one of the default implementations that we have provided, such as `PlayStorePaywallDelegate` or `RevenueCatPaywallDelegate`. > [tab] PlayStorePaywallDelegate > > Use the `PlayStorePaywallDelegate` to handle purchases using Google Play Billing. > [tab] RevenueCatPaywallDelegate > > Use the `RevenueCatPaywallDelegate` to handle purchases if your app is using RevenueCat. Make sure you add the `revenue-cat` dependency as shown in the installation section. > [tab] Custom Delegate > > You can also create a custom delegate and implement your own purchase logic. > > The `HeliumPaywallDelegate` is defined as follows: > > ```kotlin theme={null} > interface HeliumPaywallDelegate { > suspend fun makePurchase( > productDetails: ProductDetails, > basePlanId: String?, > offerId: String?, > ): HeliumPaywallTransactionStatus > suspend fun restorePurchases(): Boolean > fun onHeliumEvent(event: HeliumEvent) > } > ``` > > The `makePurchase` function is called by the Helium SDK when a user initiates a purchase. It provides you with the following parameters: > > * `productDetails`: The `ProductDetails` object from the billing library for the selected product. > * `basePlanId`: The identifier of the base plan, if applicable (for subscriptions). > * `offerId`: The identifier of the offer, if applicable (for subscriptions with special offers). ## Presenting Paywalls > [!NOTE] > > You must have a trigger and workflow configured in the [dashboard](https://app.tryhelium.com/workflows) in order to show a paywall. The recommended and simplest way to present a paywall is by using the `Helium.presentUpsell` function. This function handles the creation and presentation of the paywall activity for you. ```kotlin theme={null} // From an Activity or Fragment Helium.presentUpsell( context = this, trigger = "sdk_test" ) ``` **Helium.presentUpsell** `method` **parameters** **context** `Context` *required* The Android `Context` required to launch the paywall. Use `this` in an Activity. **trigger** `String` *required* The specific paywall trigger you want to display. **fullscreen** `Boolean` *(Optional)* A `Boolean` to determine if the paywall should be displayed in fullscreen [immersive mode](https://developer.android.com/develop/ui/views/layout/immersive), where the system bars (status and navigation) are hidden. Defaults to `false`. **disableSystemBackNavigation** `Boolean` *(Optional)* A `Boolean` to control the system back button behavior. If `true`, the back button will not close the paywall. Defaults to `false`. > [!NOTE] > > Looking for alternative presentation methods? Check out the guide on [Ways to Show a Paywall](/guides/ways-to-show-paywall). ## PaywallEventHandlers The Helium SDK allows you to listen for various paywall-related events. This is useful for tracking analytics, responding to user interactions, or handling the paywall lifecycle. There are two ways to listen for events: using the `PaywallEventHandlers` class for specific callbacks, or implementing the `HeliumEventListener` interface to receive all events. ### Option 1: Using PaywallEventHandlers You can create an instance of `PaywallEventHandlers` and provide lambdas for the events you are interested in. The available handlers are: * `onOpen`: Called when a paywall is displayed to the user. * `onClose`: Called when a paywall is closed for any reason. * `onDismissed`: Called when the user explicitly dismisses a paywall without purchasing. * `onPurchaseSucceeded`: Called when a purchase completes successfully. * `onOpenFailed`: Called when a paywall fails to open. * `onCustomPaywallAction`: Called when a custom action is triggered from the paywall. To register your handlers, use `Helium.shared.addPaywallEventListener`. You can either tie the listener to a lifecycle (recommended) or manage it manually. **Lifecycle-Aware (Recommended)** Pass a `LifecycleOwner` (like an `Activity` or `Fragment`) to have the listener automatically removed when the lifecycle is destroyed. ```kotlin theme={null} class MyActivity : AppCompatActivity() { private val paywallEventHandlers = PaywallEventHandlers( onOpen = { event -> print("Paywall opened: ${event.paywallName}") }, onClose = { event -> print("Paywall closed: ${event.paywallName}") } // ... other event handlers ) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Add the listener once, it will be cleaned up automatically Helium.shared.addPaywallEventListener(this, paywallEventHandlers) } } ``` **Manual Management** If you don't provide a `LifecycleOwner`, you are responsible for removing the listener to prevent memory leaks. ```kotlin theme={null} // Add the listener override fun onResume() { super.onResume() Helium.shared.addPaywallEventListener(paywallEventHandlers) } // Remove the listener to avoid leaks override fun onPause() { super.onPause() Helium.shared.removeHeliumEventListener(paywallEventHandlers) } ``` ### Option 2: Implementing HeliumEventListener For a more centralized approach, your class can implement the `HeliumEventListener` interface and handle all events in a single `onHeliumEvent` method. ```kotlin theme={null} // In your Activity or Fragment import com.tryhelium.paywall.core.event.HeliumEventListener import com.tryhelium.paywall.core.event.HeliumEvent import com.tryhelium.paywall.core.event.PaywallOpen import com.tryhelium.paywall.core.event.PaywallClose class MyActivity : AppCompatActivity(), HeliumEventListener { override fun onResume() { super.onResume() // Register this class as the listener Helium.shared.addPaywallEventListener(this, this) } override fun onPause() { super.onPause() // Unregister to prevent memory leaks Helium.shared.removeHeliumEventListener(this) } override fun onHeliumEvent(event: HeliumEvent) { when (event) { is PaywallOpen -> { // Handle paywall open } is PaywallClose -> { // Handle paywall close } // ... handle other event types } } } ``` > [!NOTE] > > **Usage Suggestions:** > > * Use `onDismiss` for post-paywall navigation when the paywall is dismissed but a user's entitlement hasn't changed > * Use `onPurchaseSucceeded` for your post purchase flow (e.g., a premium onboarding navigation) > * Use `onClose` to handle a paywall close, regardless of reason ## Fallbacks and Loading Budgets If a paywall has not completed downloading when you attempt to present it, a loading state can be displayed. By default, Helium will show this loading state (a shimmer view) for up to 2 seconds (`2000ms`). You can configure this behavior, turn it off, or set trigger-specific loading budgets using the `HeliumFallbackConfig` object during initialization. If the loading budget expires before the paywall is ready, a fallback paywall will be shown if one is provided. Otherwise, the loading state will hide, and a `PaywallOpenFailed` event will be dispatched. There are three options for fallbacks in the Android SDK: * **Fallback bundles**: A pre-packaged paywall bundle stored in your app's `assets` directory. * **Default fallback view**: A custom Android `View` to be used for all triggers. * **Fallback view per trigger**: A map of trigger names to specific Android `View`s. All of this is configured via the `HeliumFallbackConfig` object passed into `Helium.initialize()`. Here are some examples: **1. Providing a fallback bundle:** Place your fallback JSON file in the `src/main/assets` directory of your module. Then, initialize Helium with the `fallbackBundleName`. ```kotlin theme={null} // In your Activity's or Application's onCreate() method Helium.initialize( // ... other parameters environment = HeliumEnvironment.SANDBOX, // Or HeliumEnvironment.PRODUCTION fallbackConfig = HeliumFallbackConfig.withFallbackBundle( fallbackBundleName = "fallback-bundle-name.json" ) ) ``` **2. Providing a fallback view and configuring loading budgets:** You can also provide a custom `View` and fine-tune the loading behavior. ```kotlin theme={null} // In your Activity's or Application's onCreate() method val fallbackView = YourFallbackView(this) // Your custom fallback view Helium.initialize( // ... other parameters environment = HeliumEnvironment.SANDBOX, // Or HeliumEnvironment.PRODUCTION fallbackConfig = HeliumFallbackConfig( fallbackView = fallbackView, useLoadingState = true, // Show a loading state before fallback loadingBudgetInMs = 3000, // Global loading budget (in milliseconds) perTriggerLoadingConfig = mapOf( "onboarding" to HeliumFallbackConfig(loadingBudgetInMs = 4000), "quick_upgrade" to HeliumFallbackConfig(useLoadingState = false) ) ) ) ``` # SDK Quickstart (Flutter) Source: https://docs.tryhelium.com/sdk/quickstart-flutter Integrate Helium into your Flutter App > [!TIP] > > To get a better understanding of how paywalls are served, visit [here](/guides/how-does-helium-work). # Present a Paywall ### Install the SDK > [!NOTE] > > The minimum version of Flutter supported by this SDK is **3.24.0**. To add the Helium package, run: ```bash theme={null} flutter pub add helium_flutter ``` Or if you prefer, you can add the helium_flutter package to your pubspec.yaml: ```yaml theme={null} dependencies: helium_flutter: ^3.1.3 ``` then run: ```bash theme={null} flutter pub get ``` > [!TIP] > > **Recommended -** Make sure that Swift Package Manager support is enabled: ```bash theme={null} flutter upgrade flutter config --enable-swift-package-manager ``` See this [Flutter documentation](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers) for more details about Swift Package Manager. > [!NOTE] > > You can still use Cocoapods for your dependencies if preferred. If you need to disable Swift Package Manager dependencies after having enabled it, refer to that same [Flutter documentation](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers#how-to-turn-off-swift-package-manager). #### iOS Settings Helium requires iOS 15+. If your app already has a minimum of iOS 15 or higher, you're all set. This can be specified in your `ios/Podfile` with: ```text theme={null} platform :ios, '15.0' ``` If you still see errors related to minimum iOS version, consider updating to 15.0 or higher [directly in the Xcode project](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers#how-to-use-a-swift-package-manager-flutter-plugin-that-requires-a-higher-os-version). ### Initialize Helium > [!TIP] > > Find your API key [here](https://app.tryhelium.com/profile). If you do not have a Helium account set up yet, you can still integrate but will not be able to show a real paywall. In your app's initialization code (typically in `main.dart` or your root widget): ```dart theme={null} import 'package:helium_flutter/helium_flutter.dart'; Future main() async { WidgetsFlutterBinding.ensureInitialized(); final heliumFlutter = HeliumFlutter(); await heliumFlutter.initialize( apiKey: "", ); runApp(const MyApp()); } ``` **initialize** `method` **parameters** **apiKey** `string` *required* You can create or retrieve your api key from [Account Settings](https://app.tryhelium.com/profile). **callbacks** `HeliumCallbacks?` *(Optional)* Pass in a listener for paywall events. See the Helium Events section. **purchaseDelegate** `HeliumPurchaseDelegate?` *(Optional)* Delegate for handling your own purchase logic. If not provided, Helium will handle purchase logic for you. See the RevenueCat and Custom Purchase Handling sections. **fallbackPaywall** `Widget?` *(Optional)* A widget to display if paywall fails to display. See Fallback Paywalls section. **customUserId** `String?` *(Optional)* A custom user id to use instead of Helium's. We'll use this id when forwarding to third party analytics services, so this can be used for attribution. See Identifying Users section. **customUserTraits** `Map\?` *(Optional)* Custom user traits to be used for targeting, personalization, and dynamic paywall content. See Identifying Users section. **revenueCatAppUserId** `String?` *(Optional)* RevenueCat ONLY. Supply RevenueCat appUserID here (and initialize RevenueCat before Helium initialize). See RevenueCat section. **fallbackBundleAssetPath** `String?` *(Optional)* Path to fallback bundle. See Fallback Paywalls section. **paywallLoadingConfig** `HeliumPaywallLoadingConfig?` *(Optional)* Set loading budget in seconds and whether to show a loading state. See Fallback Paywalls section. ### Show Your First Paywall 🎉 > [!TIP] > > Set up a trigger and workflow in the [dashboard](https://app.tryhelium.com/workflows) to show your desired paywall. Create unique triggers for each location a paywall can show in your app! This provides more flexibility with paywall variation and experiments, allowing you to take full advantage of Helium. Call `presentUpsell` wherever you want to show a full-screen paywall: ```dart theme={null} ElevatedButton( onPressed: () { final heliumFlutter = HeliumFlutter(); heliumFlutter.presentUpsell(context: context, trigger: 'insert-trigger-here'); }, child: Text('Show Premium Features'), ), ``` > [!WARNING] > > Do not call `presentUpsell` in `Widget build()` as this can have unpredictable behavior. You should now be able to see Helium paywalls in your app! Well done! 🎉 > [!NOTE] > > Looking for alternative presentation methods? Check out the guide on [Ways to Show a Paywall](/guides/ways-to-show-paywall). # Recommended Setup Here are some common additional steps that you may want to consider. ### Identifying Users Identifying users is optional but can help with targeting and when forwarding events to external analytics platforms. If you are not sure, you probably do not need to identify your users. > [!TIP] > > Identify users as early as you can to maximize consistency in metrics and targeting. Ideally in your `initialize` call! ```dart Set during initialize theme={null} await heliumFlutter.initialize( apiKey: "", customUserId: "your-custom-user-id", customUserTraits: { "exampleTrait": "value", "userType": "premium", }, ); ``` ```dart Update after initialize theme={null} await heliumFlutter.overrideUserId( newUserId: "your-custom-user-id", traits: { "exampleTrait": "value", "userType": "premium", }, ); ``` ### Helium Events Helium dispatches various events during paywall presentation and purchase flow. You can optionally handle these events in your mobile app. You can also configure Helium to forward them to your [existing analytics provider](/guides/third-party-analytics). #### PaywallEventHandlers When displaying a paywall you can pass in event handlers to listen for select events: ```dart theme={null} HeliumFlutter().presentUpsell( trigger: 'my_paywall', context: context, eventHandlers: PaywallEventHandlers( onOpen: (event) { log('${event.type} - trigger: ${event.triggerName}'); }, onClose: (event) { log('${event.type} - trigger: ${event.triggerName}'); }, onDismissed: (event) { log('${event.type} - trigger: ${event.triggerName}'); }, onPurchaseSucceeded: (event) { log('${event.type} - trigger: ${event.triggerName}'); }, onAnyEvent: (event) { // A handler for all paywall-related events. // Note that if you have other handlers (i.e. onOpen) set up, // both that handler AND this one will fire during paywall open. }, ), ); ``` #### Global Event Listener You can also listen for all Helium events globally by implementing `HeliumCallbacks` and passing it to `initialize`: ```dart theme={null} abstract class HeliumCallbacks { Future onPaywallEvent(HeliumPaywallEvent heliumPaywallEvent); } ``` For example: ```dart theme={null} class LogCallbacks implements HeliumCallbacks { @override Future onPaywallEvent(HeliumPaywallEvent heliumPaywallEvent) async { log('onPaywallEvent: ${heliumPaywallEvent.type} - trigger: ${heliumPaywallEvent.triggerName}'); } } ``` Then pass it to initialize: ```dart theme={null} await heliumFlutter.initialize( apiKey: "", callbacks: LogCallbacks(), ); ``` ### Fallback Paywalls It is **highly recommended** that you set up "fallbacks" to handle the rare case when a paywall fails to display. Please follow [this guide](/guides/fallback-bundle) to do so. > [!TIP] > > Do this *after* you have a paywall created that you want to use in production. ### Checking Subscription Status & Entitlements Helium checks entitlements directly through the underlying app store (StoreKit on iOS, Google Play Billing on Android) and provides helper methods to make this easier. Consider checking entitlements to gate premium features. > [!NOTE] > > If you have a backend server that manages user entitlements, you may have no use for these helpers. > [accordion] All Entitlement Helper Methods > > Called on a `HeliumFlutter` instance: > > ```dart theme={null} > /// Checks if the user has any active subscription (including non-renewable) > Future hasAnyActiveSubscription(); > > /// Checks if the user has any entitlement > Future hasAnyEntitlement(); > > /// Checks if the user has an active entitlement for any product attached to > /// the paywall that will show for the provided trigger. > /// Returns `null` if not known (i.e. the paywall is not downloaded yet). > Future hasEntitlementForPaywall(String trigger); > ``` If you want to check entitlement status before presenting a paywall, here are a couple of ways to do so. > [!NOTE] > > For paywalls that are user-initiated (e.g. "Upgrade to Premium") and onboarding paywalls, checking entitled status is not recommended. Apps usually want to consistently show a paywall for these locations, and users can still "Restore Purchases" as needed. ```dart Use dontShowIfAlreadyEntitled with presentUpsell theme={null} heliumFlutter.presentUpsell( trigger: 'my_paywall', context: context, dontShowIfAlreadyEntitled: true ); ``` ```dart Check before showing paywall theme={null} final heliumFlutter = HeliumFlutter(); final hasActiveSubscription = await heliumFlutter.hasAnyActiveSubscription(); if (hasActiveSubscription) { featureGatedLogic(); // replace this with your logic } else { heliumFlutter.presentUpsell( trigger: 'my_paywall', context: context, eventHandlers: PaywallEventHandlers( onPurchaseSucceeded: (event) { featureGatedLogic(); // replace this with your logic }, ) ); } ``` # Advanced ### RevenueCat > [!NOTE] > > By default, Helium will handle purchases for you! This section is typically for users who already use RevenueCat in their app. Helium integrates seamlessly with RevenueCat so you can continue to let RevenueCat handle your purchases and entitlements. #### Install HeliumRevenueCat Add the **helium_revenuecat** package alongside helium_flutter: ```bash theme={null} flutter pub add helium_revenuecat ``` #### Configure Helium to use RevenueCat for Purchases Use the built-in `RevenueCatPurchaseDelegate`: ```dart theme={null} import 'package:helium_revenuecat/helium_revenuecat.dart'; final heliumFlutter = HeliumFlutter(); await heliumFlutter.initialize( apiKey: "", purchaseDelegate: RevenueCatPurchaseDelegate(), ); ``` > [!WARNING] > > Make sure to configure RevenueCat *before* initializing Helium. #### RevenueCat appUserID If you ever [change the appUserID](https://www.revenuecat.com/docs/customers/identifying-customers#logging-in-after-configuration) of a user, keep Helium in sync with: ```dart theme={null} HeliumFlutter().setRevenueCatAppUserId(await Purchases.appUserID); ``` ### Custom Purchase Handling > [!NOTE] > > By default, Helium will handle purchases for you! This section is for those who want to implement custom purchase logic. Implement `HeliumPurchaseDelegate` and pass it to `initialize`: ```dart theme={null} abstract class HeliumPurchaseDelegate { Future makePurchase(String productId); Future restorePurchases(); } ``` ### Additional Features > [!NOTE] > > For the full public API and detailed parameter documentation, see the inline docstrings in the SDK source. Import Helium in your project and use your IDE's autocomplete or jump-to-definition to explore all available methods and types. > [accordion] Checking Download Status > > > [!TIP] > > > > In most cases there is no need to check download status. Helium will display a loading indication if a paywall is presented before download has completed. > > You can listen to the status of the paywalls download via a stream: > > ```dart theme={null} > HeliumFlutter.downloadStatus.listen((status) { > print('Download status: ${status.name}'); > }); > ``` > > The download status will be one of the following: > > * `notDownloadedYet`: The download has not been initiated. > * `inProgress`: The download is in progress. > * `downloadSuccess`: The download was successful. > * `downloadFailure`: The download failed. > > You can also check if paywalls have been downloaded with `await heliumFlutter.paywallsLoaded()` > [accordion] Hiding Paywalls Programmatically > > You can programmatically hide paywalls using: > > ```dart theme={null} > // Hide the current paywall > await HeliumFlutter().hideUpsell(); > > // Hide all currently displayed paywalls > await HeliumFlutter().hideAllUpsells(); > ``` > [accordion] Reset Helium > > Reset Helium entirely so you can call initialize again, for example after changing user traits that can affect the paywalls a user might see via targeting. > > ```dart theme={null} > await HeliumFlutter().resetHelium(); > ``` # SDK Quickstart (iOS) Source: https://docs.tryhelium.com/sdk/quickstart-ios Integrate Helium into your iOS app > [!TIP] > > To get a better understanding of how paywalls are served, visit [here](/guides/how-does-helium-work). > [!NOTE] > > Migrating from v3? View [the migration guide](/migrations/ios-3-to-4). # Present a Paywall ### Install the Helium SDK > [!NOTE] > > Helium requires a minimum deployment target of iOS 15 and Xcode 14+. (Using the latest Xcode is recommended.) We recommend using Swift Package Manager (SPM) but also offer a Cocoapod. > [tab] Swift Package Manager (SPM) > > 1. In Xcode, navigate to your project's **Package Dependencies:** > > ![Spm Add Pn](https://mintcdn.com/helium/U18KGdYMLV66ysHe/images/spmadd.png?fit=max\&auto=format\&n=U18KGdYMLV66ysHe\&q=85\&s=6ca22c62f76e674fc72993b2557cf5ae) > 2. Click the **+** button and search for the Helium package URL: > ```text theme={null} > https://github.com/cloudcaptainai/helium-swift.git > ``` > > [!TIP] > > > > For **Dependency Rule** we recommend the default **Up to Next Major Version** to make sure you get non-breaking bug fixes. View the [list of releases](https://github.com/cloudcaptainai/helium-swift/releases) here. > 3. Click **Add Package**. > 4. In the dialog that appears, make sure to add the **Helium** product to your app's main target: > > ![Spm Target Pn](https://mintcdn.com/helium/U18KGdYMLV66ysHe/images/spmtarget.png?fit=max\&auto=format\&n=U18KGdYMLV66ysHe\&q=85\&s=28bd3d27f5a0797213e89d27eff257f3) > 5. Select **Add Package** in the dialog and Helium should now be ready for import. > [tab] Cocoapod > > Add this to your Podfile: > > ```ruby theme={null} > pod 'Helium', '~> 4.0' > ``` > > Then run: > > ```bash theme={null} > pod install > ``` ### Initialize Helium Initialize the Helium SDK as early as possible in your app's lifecycle. > [!TIP] > > Find your API key [here](https://app.tryhelium.com/profile). If you do not have a Helium account set up yet, you can still integrate but will not be able to show a real paywall. ```swift theme={null} Helium.shared.initialize( apiKey: "helium-api-key" ) ``` Choose the appropriate location based on your app's architecture: > [tab] SwiftUI > > ```swift theme={null} > @main > struct MyApp: App { > init() { > //*** Add this: > configureHelium() > } > > var body: some Scene { > WindowGroup { > ContentView() > } > } > > //*** And this: > private func configureHelium() { > Helium.shared.initialize(apiKey: "helium-api-key") > } > } > ``` > [tab] SceneDelegate > > ```swift theme={null} > class SceneDelegate: UIResponder, UIWindowSceneDelegate { > > var window: UIWindow? > > func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) { > //*** Add this: > configureHelium() > } > > //*** And this: > private func configureHelium() { > Helium.shared.initialize(apiKey: "helium-api-key") > } > } > ``` > [tab] AppDelegate > > ```swift theme={null} > @UIApplicationMain > class AppDelegate: UIResponder, UIApplicationDelegate { > > var window: UIWindow? > > func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { > //*** Add this: > configureHelium() > return true > } > > //*** And this: > private func configureHelium() { > Helium.shared.initialize(apiKey: "helium-api-key") > } > } > ``` And import Helium in the same file: ```swift theme={null} import Helium ``` ### Show Your First Paywall 🎉 > [!TIP] > > Set up a trigger and workflow in the [dashboard](https://app.tryhelium.com/workflows) to show your desired paywall. Create unique triggers for each location a paywall can show in your app! This provides more flexibility with paywall variation and experiments, allowing you to take full advantage of Helium. Call `presentPaywall` wherever you want to show a full-screen paywall: ```swift theme={null} Helium.shared.presentPaywall( trigger: "premium" ) { paywallNotShownReason in // Handle any scenario where the paywall does not show } ``` **Helium.shared.presentPaywall** `method` **parameters** **trigger** `String` *required* The trigger name configured in the Helium dashboard **config** `PaywallPresentationConfig?` *(Optional)* Configuration for this paywall presentation ```swift theme={null} struct PaywallPresentationConfig { // View controller to present from. Defaults to current top view controller var presentFromViewController: UIViewController? = nil // Custom traits to send to the paywall var customPaywallTraits: HeliumUserTraits? = nil // Don't show paywall if user is entitled to a product in paywall. // In most cases the default of false is desired -- see "Checking // Subscription Status & Entitlements" below before enabling this. var dontShowIfAlreadyEntitled: Bool = false // How long to allow loading state before switching to fallback logic. // Use zero or negative value to disable loading state. var loadingBudget: TimeInterval = DEFAULT_LOADING_BUDGET } ``` **eventHandlers** `PaywallEventHandlers?` *(Optional)* Event handlers for paywall lifecycle events **onEntitled** `((PaywallEntitledEvent) -\> Void)?` *(Optional)* A handler for when user is entitled to a product in the paywall, via purchase or existing entitlement. Receives a `PaywallEntitledEvent` identifying how the user became entitled: * `.purchased` — a new purchase completed successfully * `.restored` — an existing entitlement was surfaced via restore * `.alreadyEntitled` — a purchase attempt resolved to an entitlement the user already had * `.skipped` — the paywall was not shown because the user is already entitled (requires `config.dontShowIfAlreadyEntitled`) Existing no-argument closures keep working (they map to a deprecated overload). **onPaywallNotShown** `(PaywallNotShownReason) -\> Void` *required* Handle any scenario where the paywall does not show. If user is already entitled and `config.dontShowIfAlreadyEntitled` is true, `onPaywallNotShown(.alreadyEntitled)` will be called only if `onEntitled` is not provided. You should now be able to see Helium paywalls in your app! Well done! 🎉 > [!NOTE] > > Looking for alternative presentation methods? Check out the guide on [Ways to Show a Paywall](/guides/ways-to-show-paywall). # Recommended Setup Here are some common additional steps that you may want to consider. ### Identifying Users Identifying users is optional but can help with targeting and when forwarding events to external analytics platforms. If you are not sure, you probably do not need to identify your users. > [!TIP] > > Identify users as early as you can to maximize consistency in metrics and targeting. Ideally right before you call Helium.shared.initialize! Set a custom user ID ```swift theme={null} Helium.identify.userId = "custom-user-id" ``` Set custom user traits for targeting and analytics visibility ```swift theme={null} Helium.identify.setUserTraits(HeliumUserTraits(["hasOnboarded": true])) // or Helium.identify.addUserTraits() if you don't want to clear existing traits ``` > [accordion] appAccountToken > > If you use an `appAccountToken` for your existing purchases, then we recommend you also share this value with Helium so Helium can apply the `appAccountToken` to paywall purchases. > > ```swift theme={null} > if let appAccountTokenUUID = UUID(uuidString: "app-account-token-uuid") { > Helium.identify.appAccountToken = appAccountTokenUUID > } > ``` ### Helium Events Helium dispatches various events during paywall presentation and purchase flow. You can optionally handle these events in your mobile app. You can also configure Helium to forward them to your [existing analytics provider](/guides/third-party-analytics). #### PaywallEventHandlers When displaying a paywall you can pass in event handlers to listen for select events: ```swift theme={null} Helium.shared.presentPaywall( trigger: "post_onboarding", eventHandlers: PaywallEventHandlers() .onOpen { event in print("open via trigger \(event.triggerName)") } .onClose { event in print("close for trigger \(event.triggerName)") } .onDismissed { event in print("dismiss for trigger \(event.triggerName)") } .onPurchaseSucceeded { event in print("purchase succeeded for trigger \(event.triggerName)") } .onCustomPaywallAction { event in print("Custom action: \(event.actionName) with params: \(event.params)") } .onAnyEvent { event in // A handler for all paywall-related events. // Note that if you have other handlers (i.e. onOpen) set up, // both that handler AND this one will fire during paywall open. } ) { paywallNotShownReason in // handle paywall not shown } ``` #### Global Helium Event Listener You can also add one or more global event listeners. For example: ```swift theme={null} /// Implement this where you want to handle events public protocol HeliumEventListener : AnyObject { func onHeliumEvent(event: HeliumEvent) } /// Add a listener for all Helium events. public func addHeliumEventListener(_ listener: HeliumEventListener) /// Remove a specific Helium event listener. public func removeHeliumEventListener(_ listener: HeliumEventListener) ``` > [!WARNING] > > Listeners are held **weakly** to prevent memory leaks. If you don't maintain a strong reference to your listener, it will be deallocated immediately and no events will fire. ```swift theme={null} // ❌ Wrong - listener is deallocated immediately, no events will fire Helium.shared.addHeliumEventListener(MyListener()) // ✅ Works - singleton keeps a strong reference class MyHeliumEventListener: HeliumEventListener { static let shared = MyHeliumEventListener() func onHeliumEvent(event: any HeliumEvent) { print("Helium event: \(event.toDictionary())") } } // And make sure to register it: Helium.shared.addHeliumEventListener(MyHeliumEventListener.shared) ``` ### Fallback Paywalls It is **highly recommended** that you set up "fallbacks" to handle the rare case when a paywall fails to display. Please follow [this guide](/guides/fallback-bundle) to do so. > [!TIP] > > Do this *after* you have a paywall created that you want to use in production. ### Checking Subscription Status & Entitlements Helium checks entitlements directly through StoreKit and provides helper methods to make this easier. Consider checking entitlements to gate premium features. > [!NOTE] > > If you have a backend server that manages user entitlements, you may have no use for these helpers. > [accordion] List of All Entitlement Helper Methods > > Accessed from `Helium.entitlements`: > > `hasAny()` Checks if the user has purchased any subscription or non-consumable product. > > `hasAnyActiveSubscription()` Checks if the user has any active subscription. > > `hasEntitlementForPaywall(trigger: String, considerAssociatedSubscriptions: Bool = false)` Checks if the user has entitlements for any product in a specific paywall. Returns `nil` if paywall configuration hasn't been downloaded yet. > > `hasActiveEntitlementFor(productId: String)` Checks if the user has entitlement to a specific product. > > `hasActiveSubscriptionFor(productId: String)` Checks if the user has an active subscription for a specific product. > > `hasActiveSubscriptionFor(subscriptionGroupID: String)` Checks if the user has an active subscription in a specific subscription group. > > `purchasedProductIds()` Retrieves a list of all product IDs the user currently has access to. > > `activeSubscriptions()` Returns detailed information about all active auto-renewing subscriptions. > > `subscriptionStatusFor(productId: String)` Gets detailed subscription status for a specific product, including state information like subscribed, expired, or in grace period. > > `subscriptionStatusFor(subscriptionGroupID: String)` Gets detailed subscription status for a specific subscription group. If you want to check entitlement status before presenting a paywall, here are a couple of ways to do so. > [!NOTE] > > For paywalls that are user-initiated (e.g. "Upgrade to Premium") and onboarding paywalls, checking entitled status is not recommended. Apps usually want to consistently show a paywall for these locations, and users can still "Restore Purchases" as needed. ```swift Use dontShowIfAlreadyEntitled with presentPaywall theme={null} Helium.shared.presentPaywall( trigger: "my_paywall_trigger", config: PaywallPresentationConfig( dontShowIfAlreadyEntitled: true ), onEntitled: { entitledEvent in // handle user with existing entitlement // or new entitlement after they completed/restored a purchase } ) { paywallNotShownReason in // handle paywall not shown } ``` ```swift Check before showing paywall theme={null} let hasActiveSubscription = await Helium.entitlements.hasAnyActiveSubscription() if hasActiveSubscription { // access premium content } else { // show paywall } ``` # Advanced ### RevenueCat > [!NOTE] > > By default, Helium will handle purchases for you! This section is typically for users who already use RevenueCat in their app. Helium integrates seamlessly with RevenueCat so you can continue to let RevenueCat handle your purchases and entitlements. #### Install HeliumRevenueCat > [tab] Swift Package Manager (SPM) > > 1. In Xcode, navigate to your project's **Package Dependencies**. > > 2. Click the **+** button and search for the **HeliumRevenueCat** package URL: > ```text theme={null} > https://github.com/cloudcaptainai/helium-swift-revenuecat.git > ``` > > 3. Add the **HeliumRevenueCat** product to your app's main target. > > > [!WARNING] > > > > The **HeliumRevenueCat** package includes [purchases-ios-spm](https://github.com/RevenueCat/purchases-ios-spm) as a dependency, *not* [purchases-ios](https://github.com/RevenueCat/purchases-ios) and you may encounter build issues if you are using **purchases-ios** with SPM. (We recommend just switching to **purchases-ios-spm**). > [tab] Cocoapod > > Replace **Helium** with this in your Podfile: > > ```ruby theme={null} > pod 'Helium/RevenueCat', '~> 4.0' > ``` > > Then run: > > ```bash theme={null} > pod install > ``` #### Configure Helium to use RevenueCat for Purchases Simply use Helium's pre-built `RevenueCatDelegate` to let RevenueCat handle paywall purchases. ```swift theme={null} import HeliumRevenueCat // unless using Cocoapod then can just import Helium Helium.config.purchaseDelegate = RevenueCatDelegate( // Optional - pass in to have Helium handle RevenueCat initialization. revenueCatApiKey: "" ) ``` > [!WARNING] > > If you do not supply `revenueCatApiKey`, make sure to initialize RevenueCat *before* creating the RevenueCatDelegate! > [!TIP] > > It is best to do this configuration *before* you call `Helium.shared.initialize` #### RevenueCat appUserID If you ever [change the appUserID](https://www.revenuecat.com/docs/customers/identifying-customers#logging-in-after-configuration) of a user, keep Helium in sync with: ```swift theme={null} Helium.identify.revenueCatAppUserId = Purchases.shared.appUserID ``` ### Custom Purchase Handling > [!NOTE] > > By default, Helium will handle purchases for you! This section is for those who want to implement custom purchase logic. > [!TIP] > > Want to add some custom behavior but still use the built-in purchase logic? Just subclass `StoreKitDelegate` or `RevenueCatDelegate`! (Be sure to make a `super` call for any overridden methods.) You can also create a custom delegate and implement your own purchase logic. You can look at our [StoreKitDelegate](https://github.com/cloudcaptainai/helium-swift/blob/main/Sources/Helium/HeliumCore/StoreKitDelegate.swift) and [RevenueCatDelegate](https://github.com/cloudcaptainai/helium-swift/blob/main/Sources/HeliumRevenueCat/HeliumRevenueCat.swift) in the SDK for examples (also linked below). The `HeliumPaywallDelegate` is defined as follows: ```swift theme={null} public protocol HeliumPaywallDelegate: AnyObject { // Execute the purchase of a product given the product ID. func makePurchase(productId: String) async -> HeliumPaywallTransactionStatus // (Optional) - Restore any existing subscriptions. // Return a boolean indicating whether the restore was successful. func restorePurchases() async -> Bool // (Optional) - Called for all Helium events (e.g. PaywallOpenEvent) func onPaywallEvent(_ event: HeliumEvent) } ``` ### Additional Features > [!NOTE] > > For the full public API and detailed parameter documentation, see the inline docstrings in the SDK source. Import Helium in your project and use your IDE's autocomplete or jump-to-definition to explore all available methods and types. > [accordion] In-App Paywall Links > > By default, web links (`http`/`https`) opened via a paywall's navigate action open in the external browser. To open them in-app in a Safari page sheet over the paywall instead: > > ```swift theme={null} > Helium.config.openPaywallLinksInApp = true > ``` > > Non-web links (e.g. `mailto:`, `tel:`) and direct HTML anchor taps always open externally. > [accordion] Checking Download Status > > > [!TIP] > > > > In most cases there is no need to check download status. Helium will display a loading indication if a paywall is presented before download has completed. > > You can check the status of the paywall configuration download using the `Helium.shared.getDownloadStatus()` method. This method returns a value of type `HeliumFetchedConfigStatus`, which is defined as follows: > > ```swift theme={null} > public enum HeliumFetchedConfigStatus: String, Codable, Equatable { > case notDownloadedYet > case inProgress > case downloadSuccess > case downloadFailure > } > ``` > > You can also simply check if paywalls have been successfully downloaded with `Helium.shared.paywallsLoaded()`. > [accordion] Get Paywall Info By Trigger > > Retrieve basic information about the paywall for a specific trigger with `Helium.shared.getPaywallInfo(trigger: String)` which returns: > > ```swift theme={null} > public struct PaywallInfo { > public let paywallTemplateName: String > // shouldShow only false if the paywall should not be shown due to targeting or workflow configuration (Helium handles this for you in presentPaywall) > public let shouldShow: Bool > } > ``` > > > [!TIP] > > > > This method can be used if you want to be certain that a paywall is ready for display before attempting to display. > [accordion] Hiding Paywalls Programmatically > > You can programmatically hide paywalls using: > > ```swift theme={null} > // Hide the current paywall > Helium.shared.hidePaywall() > > // Hide all currently displayed paywalls > Helium.shared.hideAllPaywalls() > ``` > [accordion] Reset Helium > > Reset Helium entirely so you can call initialize again, for example after changing user traits that can affect the paywalls a user might see via targeting. > > ```swift theme={null} > Helium.resetHelium() > ``` # SDK Quickstart (iOS) Source: https://docs.tryhelium.com/sdk/quickstart-ios-v3 Legacy quickstart for Helium iOS SDK v3. New integrations should use the current iOS quickstart; v3 users should follow the v3 to v4 migration guide. ## Background Get set up with the Helium SDK for iOS. Reach out over your Helium slack channel or email [founders@tryhelium.com](mailto:founders@tryhelium.com) for any questions. ## Installation > [!NOTE] > > Helium requires a minimum deployment target of iOS 15 and Xcode 14+. (Latest Xcode is recommended.) We recommend using Swift Package Manager (SPM), but if your project primarily uses Cocoapods it might make sense to install the Helium Cocoapod instead. > [tab] Swift Package Manager (SPM) > > 1. In Xcode, navigate to your project's **Package Dependencies:** > > ![Spm Add Pn](https://mintcdn.com/helium/U18KGdYMLV66ysHe/images/spmadd.png?fit=max\&auto=format\&n=U18KGdYMLV66ysHe\&q=85\&s=6ca22c62f76e674fc72993b2557cf5ae) > > 2. Click the **+** button and search for the Helium package URL: > > ``` > https://github.com/cloudcaptainai/helium-swift.git > ``` > > > [!TIP] > > > > For **Dependency Rule** we recommend the default **Up to Next Major Version** to make sure you get non-breaking bug fixes. View the [list of releases](https://github.com/cloudcaptainai/helium-swift/releases) here. > > 3. Click **Add Package**. > > 4. In the dialog that appears, make sure to add the **Helium** product to your app's main target: > > ![Spm Target Pn](https://mintcdn.com/helium/U18KGdYMLV66ysHe/images/spmtarget.png?fit=max\&auto=format\&n=U18KGdYMLV66ysHe\&q=85\&s=28bd3d27f5a0797213e89d27eff257f3) > > 5. *(Optional)* If you are using RevenueCat to manage purchases, we recommended you also add **HeliumRevenueCat** to your target so that you can use our RevenueCatDelegate referenced in the **Purchase Handling** section of this guide. Otherwise leave as **None** for the HeliumRevenueCat row. > > > [!WARNING] > > > > The **HeliumRevenueCat** target includes [purchases-ios-spm](https://github.com/RevenueCat/purchases-ios-spm) as a dependency, *not* [purchases-ios](https://github.com/RevenueCat/purchases-ios) and you may encounter build issues if are using **purchases-ios** with SPM. (We recommend just switching to **purchases-ios-spm**). > > 6. Select **Add Package** in the dialog and Helium should now be ready for import. > [tab] Cocoapod > > ### Option 1: Core functionality only > > Add this to your Podfile: > > ```ruby theme={null} > pod 'Helium', '~> 3.0' > ``` > > Then run: > > ```bash theme={null} > pod install > ``` > > ### Option 2: Core + RevenueCat > > > [!NOTE] > > > > Recommended if you are using RevenueCat to manage purchases. > > Add this to your Podfile: > > ```ruby theme={null} > pod 'Helium/RevenueCat', '~> 3.0' > ``` > > Then run: > > ```bash theme={null} > pod install > ``` ## Initialize Helium Initialize the Helium SDK as early as possible in your app's lifecycle. Choose the appropriate location based on your app's architecture: > [tab] SwiftUI > > ```swift theme={null} > @main > struct MyApp: App { > init() { > // Call Helium.shared.initialize here (see example below) > } > > var body: some Scene { > WindowGroup { > ContentView() > } > } > } > ``` > [tab] SceneDelegate > > ```swift theme={null} > class SceneDelegate: UIResponder, UIWindowSceneDelegate { > > var window: UIWindow? > > func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) { > // Call Helium.shared.initialize here (see example below) > } > } > ``` > [tab] AppDelegate > > ```swift theme={null} > @UIApplicationMain > class AppDelegate: UIResponder, UIApplicationDelegate { > > var window: UIWindow? > > func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { > // Call Helium.shared.initialize here (see example below) > return true > } > } > ``` Add necessary imports: ```swift theme={null} import Helium ``` And initialize Helium in the location referenced above: ```swift theme={null} // Create fallback configuration with a fallback bundle // (recommended - see Fallbacks and Loading Budgets section) let fallbackBundleURL = Bundle.main.url(forResource: "fallback-bundle", withExtension: "json") let fallbackConfig = HeliumFallbackConfig.withFallbackBundle(fallbackBundleURL) Helium.shared.initialize( apiKey: "", fallbackConfig: fallbackConfig, revenueCatAppUserId: Purchases.shared.appUserID // ONLY if using RevenueCat ) ``` **Helium.shared.initialize** `method` **parameters** **apiKey** `string` *required* You can create or retrieve your api key from [Account Settings](https://app.tryhelium.com/profile). **heliumPaywallDelegate** `HeliumPaywallDelegate` *required* Delegate to handle paywall events and callbacks (see next section) **fallbackConfig** `HeliumFallbackConfig` *required* Fallback configuration with either a view or bundle URL. Required parameter. **customUserId** `String?` *(Optional)* If set, a custom user id to use instead of Helium's. We'll use this id when forwarding to third party analytics services, so this can be used for attribution (e.g. an amplitude user id, or a custom user id from your own analytics service) **customUserTraits** `HeliumUserTraits?` *(Optional)* Pass in custom user traits to be used for targeting, personalization, and dynamic content. It can be created with any dictionary, as long as the key is a string and the value is a `Codable` type. ```swift theme={null} let customUserTraits = HeliumUserTraits(traits: [ "testTrait": 1, "account_age_in_days": "20", ]) ``` **appAttributionToken** `UUID?` *(Optional)* Set this if you use a custom appAccountToken with your StoreKit purchases. **revenueCatAppUserId** `String?` *(Optional)* RevenueCat ONLY. Supply RevenueCat appUserID here (and initialize RevenueCat before Helium initialize). You can also set this value outside of initialize: `Helium.shared.setRevenueCatAppUserId(Purchases.shared.appUserID)` > [!TIP] > > No need to set this if you use RevenueCatDelegate (see next section). > [!NOTE] > > Helium's initialization is ran on a background thread, so you don't have to worry about it affecting your app's launch time. > [accordion] Custom User ID and Custom User Traits > > You can provide a custom user ID and custom user traits in the `initialize` method or by using `Helium.shared.overrideUserId`. Set the user ID and traits before or during `initialize` to ensure consistency in analytics events and for the best experimentation results. > > ```swift theme={null} > Helium.shared.overrideUserId( > newUserId: "", > traits: HeliumUserTraits? = nil > ); > ``` > [accordion] Checking Download Status > > > [!NOTE] > > > > In most cases there is no need to check download status. Helium will display a loading indication if a paywall is presented before download has completed. > > You can check the status of the paywall configuration download using the `Helium.shared.getDownloadStatus()` method. This method returns a value of type `HeliumFetchedConfigStatus`, which is defined as follows: > > ```swift theme={null} > public enum HeliumFetchedConfigStatus: String, Codable, Equatable { > case notDownloadedYet > case inProgress > case downloadSuccess > case downloadFailure > } > ``` > > You can also simply check if paywalls have been successfully downloaded with `Helium.shared.paywallsLoaded()`. ## Presenting Paywalls > [!NOTE] > > You must have a trigger and workflow configured in the [dashboard](https://app.tryhelium.com/workflows) in order to show a paywall. Call `Helium.shared.presentUpsell(trigger:)` when you want to show the paywall. For example: ```swift theme={null} Button("Try Premium") { Helium.shared.presentUpsell(trigger: "post_onboarding") } ``` **Helium.shared.presentUpsell** `method` **parameters** **trigger** `String` *required* The trigger name configured in your Helium dashboard **from** `UIViewController?` *(Optional)* The view controller to present from. If nil, uses the current top view controller **eventHandlers** `PaywallEventHandlers?` *(Optional)* Event handlers for paywall lifecycle events **customPaywallTraits** `[String: Any]?` *(Optional)* Custom traits to pass to the paywall **dontShowIfAlreadyEntitled** `Bool` (default: false) *(Optional)* If `true`, the paywall will not show if the user already has entitlements for any product in the paywall. See the Entitlements section of this guide for more details. > [!NOTE] > > Looking for alternative presentation methods? Check out the guide on [Ways to Show a Paywall](/guides/ways-to-show-paywall). ### PaywallEventHandlers When displaying a paywall you can pass in event handlers to listen for relevant [Helium Events](/guides/helium-events). You can chain a subset of handlers with builder syntax: ```swift theme={null} Helium.shared.presentUpsell( trigger: "post_onboarding", eventHandlers: PaywallEventHandlers() .onOpen { event in print("open via trigger \(event.triggerName)") } .onClose { event in print("close for trigger \(event.triggerName)") } .onDismissed { event in print("dismiss for trigger \(event.triggerName)") } .onPurchaseSucceeded { event in print("purchase succeeded for trigger \(event.triggerName)") } .onOpenFailed { event in print("open failed for trigger \(event.triggerName)") } .onCustomPaywallAction { event in print("Custom action: \(event.actionName) with params: \(event.params)") } .onAnyEvent { event in // A handler for all paywall-related events. // Note that if you have other handlers (i.e. onOpen) set up, // both that handler AND this one will fire during paywall open. } ) ``` > [!NOTE] > > **Usage Suggestions:** > > * Use `onDismiss` for post-paywall navigation when the paywall is dismissed but a user's entitlement hasn't changed > * Use `onPurchaseSucceeded` for your post purchase flow (e.g., a premium onboarding navigation) > * Use `onClose` to handle a paywall close, regardless of reason You should now be able to see Helium paywalls in your app! Well done! 🎉 ## Purchase Handling > [!TIP] > > By default, Helium will handle purchases for you! This section is for those who want to delegate purchases to RevenueCat or implement custom purchase logic. Use (or subclass) one of our pre-built `HeliumPaywallDelegate` implementations or create a custom delegate. Pass the delegate in to your `Helium.shared.initialize` call. > [tab] StoreKitDelegate > > The StoreKitDelegate (default delegate) handles purchases using native StoreKit 2: > > ```swift theme={null} > import Helium > > let delegate = StoreKitDelegate() > ``` > [tab] RevenueCatDelegate > > > [!WARNING] > > > > Make sure you included HeliumRevenueCat (for SPM) or Helium/RevenueCat (for Cocoapod) as noted in the Installation section. > > RevenueCatDelegate handle purchases through RevenueCat: > > ```swift theme={null} > import HeliumRevenueCat // unless using Cocoapod then can just import Helium > > let delegate = RevenueCatDelegate( > revenueCatApiKey: "" // Optional - pass in to have Helium to handle RevenueCat initialization. > ) > ``` > > > [!NOTE] > > > > If you do not supply `revenueCatApiKey`, make sure to initialize RevenueCat *before* initializing Helium! > [tab] Custom Delegate > > You can also create a custom delegate and implement your own purchase logic. You can look at our `StoreKitDelegate` and `RevenueCatDelegate` in the SDK for examples (also linked below). > > The `HeliumPaywallDelegate` is defined as follows: > > ```swift theme={null} > public protocol HeliumPaywallDelegate: AnyObject { > > // Execute the purchase of a product given the product ID. > func makePurchase(productId: String) async -> HeliumPaywallTransactionStatus > > // (Optional) - Restore any existing subscriptions. > // Return a boolean indicating whether the restore was successful. > func restorePurchases() async -> Bool > > // (Optional) - Handle Helium Events > func onPaywallEvent(_ event: HeliumEvent) > } > ``` > > `HeliumPaywallTransactionStatus` is an enum that defines the possible states of a paywall transaction: > > ```swift theme={null} > public enum HeliumPaywallTransactionStatus { > case purchased > case cancelled > case failed(Error) > case restored > case pending > } > ``` > > Visit [Helium Events](/guides/helium-events) for details on the different Helium paywall events. > > > [!NOTE] > > > > When executing the purchase via StoreKit 2 (recommended over StoreKit 1), please use `Product.heliumPurchase()` instead of `Product.purchase()`. For example: > > > > `let result = try await product.heliumPurchase()` > > > > This will automatically set attribution information for [revenue tracking](/guides/revenue-reporting). > > StoreKitDelegate example [here](https://github.com/cloudcaptainai/helium-swift/blob/main/Sources/Helium/HeliumCore/StoreKitDelegate.swift). > > RevenueCatDelegate example [here](https://github.com/cloudcaptainai/helium-swift/blob/main/Sources/HeliumRevenueCat/HeliumRevenueCat.swift). ## Listen for Helium Events [Helium Events](/guides/helium-events) are emitted by Helium for various paywall actions, purchase completions, and more. Options to listen for these events include: ### 1. onPaywallEvent of HeliumPaywallDelegate Subclass one of the provided `HeliumPaywallDelegate` implementations (see **Purchase Handling** section above) and override `onPaywallEvent`: ```swift theme={null} class MyStoreKitDelegate: StoreKitDelegate { override func onPaywallEvent(_ event: HeliumEvent) { switch event { case let openEvent as PaywallOpenEvent: // handle open event here break case let closeEvent as PaywallCloseEvent: break case let dismissEvent as PaywallDismissedEvent: break case let purchaseEvent as PurchaseSucceededEvent: break default: break } } } ``` > [!NOTE] > > Make sure to pass your delegate in to `Helium.shared.initialize`! ### 2. Add a HeliumEventListener ```swift theme={null} /// Implement this where you want to handle events public protocol HeliumEventListener : AnyObject { func onHeliumEvent(event: HeliumEvent) } /// Add a listener for all Helium events. Listeners are stored weakly, so if you create a listener inline it may not be retained. public func addHeliumEventListener(_ listener: HeliumEventListener) /// Remove a specific Helium event listener. public func removeHeliumEventListener(_ listener: HeliumEventListener) ``` ### 3. Use PaywallEventHandlers for paywall-specific events See the section titled PaywallEventHandlers on this page. ## Checking Subscription Status & Entitlements The Helium SDK provides several ways to check user entitlements and subscription status. > [accordion] Entitlement Helper Methods > > `hasAnyEntitlement()` Checks if the user has purchased any subscription or non-consumable product. > > `hasAnyActiveSubscription(includeNonRenewing: Bool = true)` Checks if the user has any active subscription. Set `includeNonRenewing` to `false` to check only auto-renewing subscriptions. > > `hasEntitlementForPaywall(trigger: String, considerAssociatedSubscriptions: Bool = false)` Checks if the user has entitlements for any product in a specific paywall. Returns `nil` if paywall configuration hasn't been downloaded yet. > > `hasActiveEntitlementFor(productId: String)` Checks if the user has entitlement to a specific product. > > `hasActiveSubscriptionFor(productId: String)` Checks if the user has an active subscription for a specific product. > > `hasActiveSubscriptionFor(subscriptionGroupID: String)` Checks if the user has an active subscription in a specific subscription group. > > `purchasedProductIds()` Retrieves a list of all product IDs the user currently has access to. > > `activeSubscriptions()` Returns detailed information about all active auto-renewing subscriptions. > > `subscriptionStatusFor(productId: String)` Gets detailed subscription status for a specific product, including state information like subscribed, expired, or in grace period. > > `subscriptionStatusFor(subscriptionGroupID: String)` Gets detailed subscription status for a specific subscription group. #### Example Usage > [!TIP] > > Check entitlements before showing paywalls to avoid showing a paywall to a user who should not see it. ```swift Use dontShowIfAlreadyEntitled with presentUpsell theme={null} Helium.shared.presentUpsell(trigger: "my_paywall", dontShowIfAlreadyEntitled: true) ``` ```swift Check before showing paywall theme={null} let heliumTrigger = "my_paywall" let hasActiveSubscription = await Helium.shared.hasAnyActiveSubscription() if hasActiveSubscription { // access premium content } else { // show paywall Helium.shared.presentUpsell( trigger: heliumTrigger, eventHandlers: PaywallEventHandlers() .onPurchaseSucceeded { _ in // access premium content } ) } ``` ## Fallbacks and Loading Budgets If a paywall has not completed downloading when you attempt to present it, a loading state can show. By default, Helium will show this loading state as needed (a shimmer view for up to 7 seconds). You can configure, turn off, or set trigger-specific loading budgets. If the budget expires before the paywall is ready, a fallback paywall will show if available otherwise the loading state will hide and a [PaywallOpenFailed](/guides/helium-events) event will be dispatched. The iOS sdk has 3 options for fallbacks: 1. [Fallback bundles](/guides/fallback-bundle) 2. Default fallback view 3. Fallback view per trigger All of this is configured via the `HeliumFallbackConfig` object passed in to `initialize`. Here are some examples: ```swift theme={null} // Just provide a fallback bundle let fallbackBundleURL = Bundle.main.url( forResource: "fallback-bundle-xxxx-xx-xx", withExtension: "json" ) let fallbackConfig = HeliumFallbackConfig.withFallbackBundle(fallbackBundleURL) // Provide fallback view and configure loading budgets let fallbackConfig = HeliumFallbackConfig( fallbackView: YourFallbackView(), // Global loading budget (in seconds) loadingBudget: 5.0, // Per-trigger loading budgets perTriggerLoadingConfig: [ "onboarding": TriggerLoadingConfig(loadingBudget: 4), "quick_upgrade": TriggerLoadingConfig(useLoadingState: false), ] ) Helium.shared.initialize( apiKey: "your-api-key", fallbackConfig: fallbackConfig ) ``` ## Advanced > [accordion] Get Paywall Info By Trigger > > Retrieve basic information about the paywall for a specific trigger with `Helium.shared.getPaywallInfo(trigger: String)` which returns: > > ```swift theme={null} > public struct PaywallInfo { > public let paywallTemplateName: String > // shouldShow only false if the paywall should not be shown due to targeting or workflow configuration (Helium handles this for you in presentUpsell) > public let shouldShow: Bool > } > ``` > > > [!TIP] > > > > This method can be used if you want to be certain that a paywall is ready for display before displaying. > [accordion] Reset Helium > > Reset Helium entirely so you can call initialize again. Only for advanced use cases. > > ```swift theme={null} > Helium.resetHelium() > ``` # SDK Quickstart (React Native) Source: https://docs.tryhelium.com/sdk/quickstart-react-native Integrate Helium into your React Native App. > [!TIP] > > To get a better understanding of how paywalls are served, visit [here](/guides/how-does-helium-work). # Present a Paywall ### Install the SDK Install the SDK using your preferred package manager: ```bash Expo 52+ theme={null} npx expo install expo-helium ``` ```bash Older Expo / Bare theme={null} npm install @tryheliumai/paywall-sdk-react-native # or yarn add @tryheliumai/paywall-sdk-react-native # [Bare React Native] the native module autolinks; install pods cd ios && pod install # [Expo 49-51] regenerate the native projects instead npx expo prebuild ``` > [!TIP] > > We support Expo 49+ but recommend using Helium with **Expo 53+**. > [!NOTE] > > The Older Expo / Bare SDK requires React Native 0.71.7+, iOS 15+, and Android minSdk 24. ### Initialize Helium > [!TIP] > > Find your API key [here](https://app.tryhelium.com/profile). If you do not have a Helium account set up yet, you can still integrate but will not be able to show a real paywall. Initialize Helium by calling `initialize()` early in your app's lifecycle, typically in your root component: ```tsx Expo 52+ theme={null} import { initialize } from 'expo-helium'; function App() { const asyncHeliumInit = async () => { await initialize({ apiKey: '', }); }; useEffect(() => { void asyncHeliumInit(); }, []); } ``` ```tsx Older Expo / Bare theme={null} import { initialize } from '@tryheliumai/paywall-sdk-react-native'; function App() { const asyncHeliumInit = async () => { await initialize({ apiKey: '', }); }; useEffect(() => { void asyncHeliumInit(); }, []); } ``` ### Show Your First Paywall 🎉 > [!TIP] > > Set up a trigger and workflow in the [dashboard](https://app.tryhelium.com/workflows) to show your desired paywall. Create unique triggers for each location a paywall can show in your app! This provides more flexibility with paywall variation and experiments, allowing you to take full advantage of Helium. Call `presentUpsell` wherever you want to show a full-screen paywall: ```tsx Expo 52+ theme={null} import { presentUpsell } from 'expo-helium'; function YourComponent() { const handlePremiumPress = () => { presentUpsell({ triggerName: 'premium_feature_press', }); }; return (