# TASK JOURNAL
Source: https://documentation.qonversion.io/TASK_JOURNAL



# Task Journal — WP-3.4 docs fact-check round 1 (pipeline P6)

## Task

* **linear-id:** none
* **track:** docs-improvement WP-3.4 (`../docs-improvement/PLAN.md` §5.4 P6, §5.2 map)
* **title:** First fact-check pass over top funnel pages (Tier A, 16 pages)
* **worktree:** documentation\_mintlify.worktrees/docs-factcheck (branch `docs/fact-check-r1`)
* **skill:** `.claude/skills/docs-fact-check/SKILL.md`

## Goal

For each of 16 Tier-A pages: extract checkable claims (SDK signatures/method
names, version tables, API fields, limits, UI steps, stated negatives) → verify
against the source-of-truth map (gh for SDK repos, local repos for
backends/spec, rest-api-v4.yaml for API) → verdict confirmed/drift/unverifiable
→ record in `verification.json`. Only `verification.json` + this journal may be
edited; content .mdx are owned by parallel agents — drifts go to the report only.

## Scope (16)

quickstart, install-sdk, ios-sdk-setup, android-sdk, react-native-sdk,
flutter-sdk, entitlements, create-products, user-properties, user-identifiers,
testing, handling-errors, rate-limits, reference/v4/overview,
reference/v4/authentication, snippets/code/init-sdk.

## Roadmap

* [x] Read all 16 pages
* [x] SDK version checks (releases): android 8.+ (DRIFT->9), flutter ^11 ok, RN pkg ok, ios ok
* [x] init-sdk snippet: init method + LaunchMode enum all 8 platforms — CONFIRMED
* [x] user-properties / user-identifiers / testing: method signatures + enums — CONFIRMED
* [x] handling-errors: error-code enum table vs QONErrors.h — CONFIRMED (all Int values)
* [x] rate-limits: 5 req/s vs android NetworkModule (=5) — CONFIRMED; version table unverifiable
* [x] create-products: Android 9+/Billing 8 basePlanId CONFIRMED; Stripe/Paddle prefixes unverifiable (3rd-party)
* [x] reference v4 overview + authentication vs rest-api-v4.yaml + api-gateway — CONFIRMED
* [x] Write verification.json (16 entries)
* [ ] Commit verification.json + journal

## Decisions

* SDK repos not checked out locally → verify via gh (search code / release list).
* Backends, mcp-server, spec are local under /Users/smejl/Desktop/github.com/qonversion/.
* Version-table check first (cheapest, highest value per skill).

## Findings

Drifts (report only — parallel agents own the .mdx):

* **android-sdk.mdx (MEDIUM)**: install snippet `io.qonversion.android.sdk:sdk:8.+`
  but latest Android major is **9** (release sdk/9.6.0, 2026-07-21). Should be
  `9.+`. Contradicts create-products.mdx ("Android SDK 9+ / Billing Library 8").
* **user-properties.mdx (LOW)**: defined-property table omits SDK enum member
  `TenjinAnalyticsInstallationId('_q_tenjin_aiid')`; display name
  `AppMetricalProfileId` is a typo vs SDK `AppMetricaUserProfileId` (key matches).

Unverifiable (surface to user, do not delete):

* rate-limits.mdx per-platform "rate limit added in version" table (iOS 5.1.1,
  Android 6.1.1, RN 6.1.0, Flutter 7.1.0, Unity 6.1.0, Cordova 4.1.0, Cap 0.1.0)
  — historical intro versions, not walked per-repo this pass.
* create-products.mdx Stripe `prod_` / Paddle `pro_` ID prefixes — third-party
  formats, outside our repos (correct per Stripe/Paddle conventions).
* testing.mdx Apple/Google sandbox renewal-rate table — third-party console
  behaviour; Tier-A cadence is the only guard.
* entitlements/create-products/testing dashboard UI steps — not walked in
  dash-mono this pass (low risk).

Everything else CONFIRMED against source (see verification.json).

## Dead Ends

* `gh search code` hit the 403 secondary rate limit mid-pass; switched to
  `gh api .../contents ... -H "Accept: application/vnd.github.raw+json"` (separate
  budget) to read whole SDK files. No pipes allowed → base64 decode via jq blocked;
  raw accept header avoids it.

## Next Action

Fact-check follow-up fixes shipped on docs/factcheck-fixes (2026-07-25):
android-sdk gradle pin 8.+ -> 9.+ (latest major 9.6.0), user-properties table
(AppMetricaUserProfileId typo fixed + TenjinAnalyticsInstallationId row added),
macos-catalyst wired to the NextStepsChooseMode snippet (the 8th SDK-setup page,
missed by WP-3.1 ownership). Remaining: WP-3.2 screenshots (in flight).


# Get active subscriptions chart data
Source: https://documentation.qonversion.io/api-reference/analytics-charts/get-active-subscriptions-chart-data

/api-reference/analytics-api.yaml get /{projectApiKey}/chart/active-subscriptions
Retrieve active subscriptions analytics. Product filters and segmentation. filter[user_id] and filter[device_id] are NOT applied.




# Get paid subscriptions movement chart data
Source: https://documentation.qonversion.io/api-reference/analytics-charts/get-paid-subscriptions-movement-chart-data

/api-reference/analytics-api.yaml get /{projectApiKey}/chart/paid-subscriptions-movement
Retrieve paid subscriptions movement analytics. Common + product filters only. Segmentation, filter[user_id], and filter[device_id] are NOT applied.




# Get proceeds chart data
Source: https://documentation.qonversion.io/api-reference/analytics-charts/get-proceeds-chart-data

/api-reference/analytics-api.yaml get /{projectApiKey}/chart/proceeds
Retrieve proceeds analytics. All filters and segmentation supported.




# Get users overview chart data
Source: https://documentation.qonversion.io/api-reference/analytics-charts/get-users-overview-chart-data

/api-reference/analytics-api.yaml get /{projectApiKey}/chart/users-overview
Retrieve users overview analytics. User filters and segmentation, no product filters.




# Get analytics card data
Source: https://documentation.qonversion.io/api-reference/analytics/get-analytics-card-data

/api-reference/rest-api-v4.yaml get /analytics/cards/{card_code}
Returns the current value of a scalar dashboard card. Cards bundle several
related metrics (e.g. `realtime` returns today's trials, subscriptions,
in-app purchases and tracked revenue as a four-row table).

Valid public card codes:
  * `realtime` — today-so-far vs. yesterday counters
    (`trials_count`, `subscriptions_count`, `inapp_count`, `tracked_revenue`).

Additional codes are internal-only and return 404 when requested publicly.




# Get analytics chart data
Source: https://documentation.qonversion.io/api-reference/analytics/get-analytics-chart-data

/api-reference/rest-api-v4.yaml get /analytics/charts/{chart_code}
Returns time-series data for a chart. `chart_code` selects the metric; pass query
parameters to constrain the time range and segmentation.

Public chart codes (25 total) — see `enum` for the full machine-readable list:

- **Revenue**: `proceeds` (net), `sales` (gross), `refunds`, `refund-rate`, `arpu`, `arppu`.
- **Recurring revenue**: `mrr`, `arr`, `mrr-movement`, `arr-movement` (new / expansion / contraction / churn).
- **Subscriptions**: `active-subscriptions`, `new-subscriptions`, `paid-subscriptions-movement`, `subscriptions-overview`, `subscription-cancellation`.
- **Trials**: `free-trials`, `active-trials`, `trials-movement`, `trial-cancellation`, `trial-to-paid`.
- **Acquisition / conversion**: `users-overview`, `user-to-trial`, `user-to-paid`.
- **Back-compat aliases** (factory maps to canonical executor): `user-to-trial-conversion` = `user-to-trial`, `subscription-cancellation-rate` = `subscription-cancellation`.

Codes deferred to v4 api 2.0 (currently return 404): `cohort-revenue`,
`cohort-active-subscriptions`, `experiment-new-users`, `experiment-users-to-trials`,
`experiment-users-to-paid`, `refund-keeper`, `events`.

Segmentation codes (pass via `segmentation`) and filter attribute codes
(pass via `filter[<attribute>][]`) are discoverable from
`GET /v4/analytics/charts/{chart_code}/meta`.




# Get analytics chart metadata
Source: https://documentation.qonversion.io/api-reference/analytics/get-analytics-chart-metadata

/api-reference/rest-api-v4.yaml get /analytics/charts/{chart_code}/meta
Returns the chart's display metadata: available filter attributes and their
concrete values (pre-scoped to the project), available segmentation dimensions,
supported time units, and chart types. Use this to build a UI / discover the
`filter[<attribute>][]` and `segmentation` values for
`GET /v4/analytics/charts/{chart_code}`.




# Get analytics insights
Source: https://documentation.qonversion.io/api-reference/analytics/get-analytics-insights

/api-reference/rest-api-v4.yaml get /analytics/insights
Returns AI-generated insights for the project over the last `period` days.
Responses are cached on the upstream; pass `force=true` to regenerate.
The `insights[]` array groups observations by type (`critical`, `positive`,
`tip`, `info`) — each item has a short `title`, a longer `body`, and a
suggested `action`.




# Get cohort analytics data
Source: https://documentation.qonversion.io/api-reference/analytics/get-cohort-analytics-data

/api-reference/rest-api-v4.yaml get /analytics/cohorts
Returns cohort-over-time tables for the project. A cohort is a group of users
sharing an acquisition event (see `cohort_definition`). Rows are cohorts,
columns are time offsets (see `grouping`). Cells are the `metric` (revenue,
subscriptions, payers, ARPU, ARPPU).

Use `GET /v4/analytics/cohorts/meta` to discover valid filter attributes and
their concrete values for the project.




# Get cohort analytics metadata
Source: https://documentation.qonversion.io/api-reference/analytics/get-cohort-analytics-metadata

/api-reference/rest-api-v4.yaml get /analytics/cohorts/meta
Returns the discrete value sets needed to build a cohort query: available
`mode`s, `grouping`s, `metric`s, `cohort_definition`s, and filter attributes
with their concrete values (pre-scoped to the project).




# Get LTV analytics data
Source: https://documentation.qonversion.io/api-reference/analytics/get-ltv-analytics-data

/api-reference/rest-api-v4.yaml get /analytics/ltv
Returns lifetime-value curves for cohorts in the requested range. `series`
is a list of time-indexed revenue (or ARPU / ARPPU) points; `segment` +
`segments` let you split the curve by an attribute.




# Get LTV analytics metadata
Source: https://documentation.qonversion.io/api-reference/analytics/get-ltv-analytics-metadata

/api-reference/rest-api-v4.yaml get /analytics/ltv/meta
Returns available `mode`s, `segmentation` attributes, and project-scoped
filter attribute values for the LTV endpoint.




# Get LTV trial-conversion analytics data
Source: https://documentation.qonversion.io/api-reference/analytics/get-ltv-trial-conversion-analytics-data

/api-reference/rest-api-v4.yaml get /analytics/ltv/trial-conversion
Returns the trial→paid conversion rate for the requested cohort range — number of
trials started, number that converted, and the conversion rate as a decimal
(0.0–1.0). Accepts the same filter and `mode`/`revenue_type` shape as the LTV
chart endpoint.




# Get supported analytics currencies
Source: https://documentation.qonversion.io/api-reference/analytics/get-supported-analytics-currencies

/api-reference/rest-api-v4.yaml get /analytics/currencies
Returns the list of three-letter ISO 4217 currency codes accepted by the
`currency` query parameter across analytics endpoints. `USD` is always first
and is the implicit default when `currency` is omitted.




# Create an automation
Source: https://documentation.qonversion.io/api-reference/automations/create-an-automation

/api-reference/rest-api-v4.yaml post /automations
Deprecated — the Automations product surface has been removed; this API remains available for existing integrations only. Creates a new automation for the authenticated project.



# Delete an automation
Source: https://documentation.qonversion.io/api-reference/automations/delete-an-automation

/api-reference/rest-api-v4.yaml delete /automations/{automation_id}
Deprecated — the Automations product surface has been removed; this API remains available for existing integrations only. Permanently deletes an automation by ID.



# Get an automation
Source: https://documentation.qonversion.io/api-reference/automations/get-an-automation

/api-reference/rest-api-v4.yaml get /automations/{automation_id}
Deprecated — the Automations product surface has been removed; this API remains available for existing integrations only. Returns a single automation by ID.



# List automations
Source: https://documentation.qonversion.io/api-reference/automations/list-automations

/api-reference/rest-api-v4.yaml get /automations
Deprecated — the Automations product surface has been removed; this API remains available for existing integrations only. Returns a paginated list of automations for the authenticated project.
Automations are ordered by ID (descending).
Supports cursor-based pagination via `limit` and `starting_after`.




# Update an automation
Source: https://documentation.qonversion.io/api-reference/automations/update-an-automation

/api-reference/rest-api-v4.yaml put /automations/{automation_id}
Deprecated — the Automations product surface has been removed; this API remains available for existing integrations only. Fully replaces an automation's mutable fields. All mutable fields must be provided.



# Update automation status
Source: https://documentation.qonversion.io/api-reference/automations/update-automation-status

/api-reference/rest-api-v4.yaml patch /automations/{automation_id}/status
Deprecated — the Automations product surface has been removed; this API remains available for existing integrations only. Toggles the status of an automation between `active` and `inactive`.



# Delete a customer (GDPR)
Source: https://documentation.qonversion.io/api-reference/customers/delete-a-customer-gdpr

/api-reference/rest-api-v4.yaml delete /customers/{customer_id}
Permanently deletes a customer and all associated personal data.
This operation is irreversible and intended for GDPR right-to-erasure requests.
Returns 204 on success.




# Get a customer
Source: https://documentation.qonversion.io/api-reference/customers/get-a-customer

/api-reference/rest-api-v4.yaml get /customers/{customer_id}
Returns a single customer by ID.



# Get aggregated customer metrics
Source: https://documentation.qonversion.io/api-reference/customers/get-aggregated-customer-metrics

/api-reference/rest-api-v4.yaml get /customers/metrics
Returns aggregated metrics for customers of the authenticated project.



# Get customer metrics (Analytics)
Source: https://documentation.qonversion.io/api-reference/customers/get-customer-metrics-analytics

/api-reference/analytics-api.yaml get /{projectApiKey}/customers-metrics
Retrieve aggregated customer metrics for a project. Accepts the same filters and `search` as the customers list (no `page`, `limit`, or sort).

Returns counts (active subscribers, churned subscribers, active trials, billing-retry users), percentages (cancelled-trial rate, churned-subscriber rate), monetary aggregates (total sales, average price), and average payment count.




# Get customers list
Source: https://documentation.qonversion.io/api-reference/customers/get-customers-list

/api-reference/analytics-api.yaml get /{projectApiKey}/customers
Retrieve a paginated list of customers with optional filters and search.

Example:
```bash
curl "https://api.qonversion.io/v1/analytics/JFPATc4VaaWYsfurml3qZ4zsmNw0VfWH/customers?page=1&limit=20&sort_by=since&sort_order=desc&environment=1"
```

**Pagination:** Pages are 1-based at the public boundary. `page=1` returns the first page. Compute `total_pages` from the response as `ceil(total_count / limit)`; the response itself does not contain a `total_pages` field.




# Grant a permission to a customer
Source: https://documentation.qonversion.io/api-reference/customers/grant-a-permission-to-a-customer

/api-reference/rest-api-v4.yaml post /customers/{customer_id}/permissions
Grants a permission to the specified customer.
Returns 201 with a Location header pointing to the new permission resource.
If `expires_at` is provided it must be a valid RFC 3339 / ISO 8601 timestamp.




# List customer permissions
Source: https://documentation.qonversion.io/api-reference/customers/list-customer-permissions

/api-reference/rest-api-v4.yaml get /customers/{customer_id}/permissions
Returns a list of all active permissions for the specified customer.



# List customers
Source: https://documentation.qonversion.io/api-reference/customers/list-customers

/api-reference/rest-api-v4.yaml get /customers
Returns a paginated list of customers for the authenticated project.
Manifest-compliant: list envelope, ISO 8601 timestamps.




# Revoke a customer permission
Source: https://documentation.qonversion.io/api-reference/customers/revoke-a-customer-permission

/api-reference/rest-api-v4.yaml delete /customers/{customer_id}/permissions/{permission_id}
Revokes a specific permission from a customer.
Returns 204 on success. Returns 404 if the customer or permission does not exist.




# Set customer properties
Source: https://documentation.qonversion.io/api-reference/customers/set-customer-properties

/api-reference/rest-api-v4.yaml post /customers/{customer_id}/properties
Sets one or more custom properties on a customer.
Accepts up to 100 key/value pairs per request.
Keys must be 1–256 characters; values must be at most 1024 characters.




# Create an entitlement definition
Source: https://documentation.qonversion.io/api-reference/entitlements/create-an-entitlement-definition

/api-reference/rest-api-v4.yaml post /entitlements
Creates a new entitlement definition for the authenticated project.



# Delete an entitlement definition
Source: https://documentation.qonversion.io/api-reference/entitlements/delete-an-entitlement-definition

/api-reference/rest-api-v4.yaml delete /entitlements/{entitlement_id}
Deletes an entitlement definition by ID. Returns 204 on success. Returns 404 if not found.



# Get an entitlement definition
Source: https://documentation.qonversion.io/api-reference/entitlements/get-an-entitlement-definition

/api-reference/rest-api-v4.yaml get /entitlements/{entitlement_id}
Returns a single entitlement definition by ID.



# Grant an entitlement
Source: https://documentation.qonversion.io/api-reference/entitlements/grant-an-entitlement

/api-reference/rest-api.yaml post /users/{user_id}/entitlements
Manually grants an entitlement to a user. **Requires Secret Key authentication.**


<Warning>This endpoint requires a **Secret Key** (`sk_` prefix). Never expose it in client-side code.</Warning>


# Grant an entitlement to a user
Source: https://documentation.qonversion.io/api-reference/entitlements/grant-an-entitlement-to-a-user

/api-reference/rest-api-v4.yaml post /users/{user_id}/entitlements
Grants an entitlement definition to a specific user, optionally with an expiry time. Attempting to extend or modify a user entitlement whose source is a paid purchase (store or Stripe) returns `422 paid_entitlement`.



# List entitlement definitions
Source: https://documentation.qonversion.io/api-reference/entitlements/list-entitlement-definitions

/api-reference/rest-api-v4.yaml get /entitlements
Returns a paginated list of entitlement definitions for the authenticated project.
Entitlements are ordered by creation date (newest first).




# List user entitlements
Source: https://documentation.qonversion.io/api-reference/entitlements/list-user-entitlements

/api-reference/rest-api-v4.yaml get /users/{user_id}/entitlements
Returns all entitlements currently granted to the specified user. The response is wrapped in the standard list envelope, but pagination is not supported on this endpoint — `has_more` is always `false` and the full set is returned in a single call.



# Retrieve entitlements
Source: https://documentation.qonversion.io/api-reference/entitlements/retrieve-entitlements

/api-reference/rest-api.yaml get /users/{user_id}/entitlements
Retrieves all entitlements for a user.



# Revoke a user entitlement
Source: https://documentation.qonversion.io/api-reference/entitlements/revoke-a-user-entitlement

/api-reference/rest-api-v4.yaml delete /users/{user_id}/entitlements/{entitlement_id}
Revokes a previously granted entitlement from a user. Only entitlements whose source is `manual` can be revoked. Returns 204 on success, 404 if the entitlement is not active for the user, and `422 paid_entitlement` when the entitlement came from a paid purchase (store or Stripe).



# Revoke an entitlement
Source: https://documentation.qonversion.io/api-reference/entitlements/revoke-an-entitlement

/api-reference/rest-api.yaml delete /users/{user_id}/entitlements/{id}
Revokes a manually granted entitlement from a user. **Requires Secret Key authentication.**

You can only revoke entitlements with source `manual`.


<Warning>This endpoint requires a **Secret Key** (`sk_` prefix). Only entitlements with source `manual` can be revoked.</Warning>


# Update an entitlement definition (partial)
Source: https://documentation.qonversion.io/api-reference/entitlements/update-an-entitlement-definition-partial

/api-reference/rest-api-v4.yaml patch /entitlements/{entitlement_id}



# List events
Source: https://documentation.qonversion.io/api-reference/events/list-events

/api-reference/rest-api-v4.yaml get /events
Returns a list of event definitions (track events) for the authenticated project. Events are emitted by the SDK and represent subscription lifecycle and user behavior.



# Attach a user to an experiment group
Source: https://documentation.qonversion.io/api-reference/experiments/attach-a-user-to-an-experiment-group

/api-reference/rest-api-v4.yaml post /experiments/{experiment_id}/users/{user_id}
Manually assigns a user to a specific experiment group. The assignment persists; raising traffic later does not re-admit previously rejected users, and finishing the experiment releases all users. It also invalidates the SDK's in-memory config cache.



# Change experiment status
Source: https://documentation.qonversion.io/api-reference/experiments/change-experiment-status

/api-reference/rest-api-v4.yaml post /experiments/{experiment_id}/status
Changes the status of an experiment (e.g. start, pause, finish).



# Create an experiment
Source: https://documentation.qonversion.io/api-reference/experiments/create-an-experiment

/api-reference/rest-api-v4.yaml post /experiments
Creates a new experiment. Returns 201 with the created experiment and Location header.



# Create an experiment group
Source: https://documentation.qonversion.io/api-reference/experiments/create-an-experiment-group

/api-reference/rest-api-v4.yaml post /experiments/{experiment_id}/groups
Creates a new group for the specified experiment. Returns 201 with Location header.



# Delete an experiment
Source: https://documentation.qonversion.io/api-reference/experiments/delete-an-experiment

/api-reference/rest-api-v4.yaml delete /experiments/{experiment_id}
Deletes an experiment by ID. Returns 204 on success.



# Delete an experiment group
Source: https://documentation.qonversion.io/api-reference/experiments/delete-an-experiment-group

/api-reference/rest-api-v4.yaml delete /experiments/{experiment_id}/groups/{group_id}
Deletes the specified experiment group. Returns 204 on success.



# Detach a user from an experiment
Source: https://documentation.qonversion.io/api-reference/experiments/detach-a-user-from-an-experiment

/api-reference/rest-api-v4.yaml delete /experiments/{experiment_id}/users/{user_id}
Removes a user's assignment from an experiment, invalidates the SDK's in-memory config cache, and makes the user eligible for automatic experiment assignment on subsequent requests.



# Get an experiment
Source: https://documentation.qonversion.io/api-reference/experiments/get-an-experiment

/api-reference/rest-api-v4.yaml get /experiments/{experiment_id}
Returns a single experiment by ID.



# Get experiments analytics summary
Source: https://documentation.qonversion.io/api-reference/experiments/get-experiments-analytics-summary

/api-reference/rest-api-v4.yaml get /experiments/summary
Returns aggregated analytics summary for experiments.



# List experiment groups
Source: https://documentation.qonversion.io/api-reference/experiments/list-experiment-groups

/api-reference/rest-api-v4.yaml get /experiments/{experiment_id}/groups
Returns all groups for the specified experiment.



# List experiments
Source: https://documentation.qonversion.io/api-reference/experiments/list-experiments

/api-reference/rest-api-v4.yaml get /experiments
Returns all experiments for the authenticated project.



# Partially update an experiment
Source: https://documentation.qonversion.io/api-reference/experiments/partially-update-an-experiment

/api-reference/rest-api-v4.yaml patch /experiments/{experiment_id}
Updates specified fields of an experiment. Only provided fields are updated.



# Update an experiment group
Source: https://documentation.qonversion.io/api-reference/experiments/update-an-experiment-group

/api-reference/rest-api-v4.yaml patch /experiments/{experiment_id}/groups/{group_id}
Updates fields of the specified experiment group. All fields optional.



# Create export (async)
Source: https://documentation.qonversion.io/api-reference/exports/create-export-async

/api-reference/rest-api-v4.yaml post /exports
Creates a new data export task. Returns 202 Accepted with a Location
header pointing to the status endpoint. Exports are project-scoped
and require the RAW_DATA_ACCESS feature.




# Get export status
Source: https://documentation.qonversion.io/api-reference/exports/get-export-status

/api-reference/rest-api-v4.yaml get /exports/{export_id}
Check the status of an export or download the result.



# List past exports
Source: https://documentation.qonversion.io/api-reference/exports/list-past-exports

/api-reference/rest-api-v4.yaml get /exports/history
Returns a list of past exports for the authenticated project.



# Create an identity link
Source: https://documentation.qonversion.io/api-reference/identities/create-an-identity-link

/api-reference/rest-api-v4.yaml post /identities
Links a Qonversion anonymous user to an external identity ID.
If `user_id` is null, a new user is created and linked.
This is the mechanism for matching Qonversion anonymous users with your own user IDs.




# Get an identity by external ID
Source: https://documentation.qonversion.io/api-reference/identities/get-an-identity-by-external-id

/api-reference/rest-api-v4.yaml get /identities/{identity_id}
Returns the identity linked to the specified external ID.
An identity represents the association between a Qonversion anonymous user
and an external user identifier from your system.




# Create an identity
Source: https://documentation.qonversion.io/api-reference/identity/create-an-identity

/api-reference/rest-api.yaml post /identities/{identity_id}
Creates an identity. If `user_id` is not provided, a new Qonversion user is created automatically.




# Retrieve an identity
Source: https://documentation.qonversion.io/api-reference/identity/retrieve-an-identity

/api-reference/rest-api.yaml get /identities/{identity_id}
Retrieves an identity by its ID.

<Info>Identities map your internal user IDs to Qonversion User IDs, enabling cross-platform user tracking.</Info>


# Create integration
Source: https://documentation.qonversion.io/api-reference/integrations/create-integration

/api-reference/rest-api-v4.yaml post /integrations
Creates a new integration for the project.



# Delete integration
Source: https://documentation.qonversion.io/api-reference/integrations/delete-integration

/api-reference/rest-api-v4.yaml delete /integrations/{integration_id}
Permanently deletes an integration.



# Get integrations metadata
Source: https://documentation.qonversion.io/api-reference/integrations/get-integrations-metadata

/api-reference/rest-api-v4.yaml get /integrations/meta
Returns the catalog of supported integration providers grouped by category.
Each item exposes its `slug` (use as `integration` in `POST /v4/integrations`)
and `allowedStores` (the subset of `target_platform` values the provider supports).
Per-provider credential schemas are **not** returned — credentials are configured
out-of-band after the integration record is created.




# List integrations
Source: https://documentation.qonversion.io/api-reference/integrations/list-integrations

/api-reference/rest-api-v4.yaml get /integrations
Returns every integration configured for the project. There is no cursor
or offset pagination: the full set is returned in a single call and
`has_more` is always `false`.




# Update integration status
Source: https://documentation.qonversion.io/api-reference/integrations/update-integration-status

/api-reference/rest-api-v4.yaml post /integrations/{integration_id}/status
Enables or disables an integration.



# Create an offering
Source: https://documentation.qonversion.io/api-reference/offerings/create-an-offering

/api-reference/rest-api-v4.yaml post /offerings
Legacy — Offerings are superseded by Remote Configs; create Remote Configs for new integrations instead. Creates a new offering for the authenticated project. If the project has no offerings yet, the new one is auto-promoted to main (`tag` will be `1` in the response even if it was omitted in the request). Prefer `POST /v4/offerings/{offering_id}/set-main` over passing `tag=1` here when switching the main of an existing project.



# Delete an offering
Source: https://documentation.qonversion.io/api-reference/offerings/delete-an-offering

/api-reference/rest-api-v4.yaml delete /offerings/{offering_id}
Legacy — Offerings are superseded by Remote Configs; use Remote Configs for new integrations. Removes the offering and its product attachments. Experiment-variant offerings (owned by the experiments service) cannot be deleted via this API and return `422`.



# Get an offering
Source: https://documentation.qonversion.io/api-reference/offerings/get-an-offering

/api-reference/rest-api-v4.yaml get /offerings/{offering_id}
Legacy — Offerings are superseded by Remote Configs; use Remote Configs for new integrations. Returns a single offering by ID.



# List offerings
Source: https://documentation.qonversion.io/api-reference/offerings/list-offerings

/api-reference/rest-api-v4.yaml get /offerings
Legacy — Offerings are superseded by Remote Configs; use Remote Configs for new integrations. Returns regular offerings only. Experiment-variant offerings (owned by the experiments service) are excluded.



# Set main offering
Source: https://documentation.qonversion.io/api-reference/offerings/set-main-offering

/api-reference/rest-api-v4.yaml post /offerings/{offering_id}/set-main
Legacy — Offerings are superseded by Remote Configs; use Remote Configs for new integrations.

Atomically marks the offering as the project's main offering
(`tag = 1`) and clears the previous main (`tag = 0`), inside a single
transaction. No request body required — the action target is fully
identified by the path parameter. Pass an `Idempotency-Key` header to
make retries safe (the same key replays the original response).
Experiment-variant offerings return `422` (typed code
`cannot_setmain_experiment_variant`).




# Update an offering
Source: https://documentation.qonversion.io/api-reference/offerings/update-an-offering

/api-reference/rest-api-v4.yaml patch /offerings/{offering_id}
Legacy — Offerings are superseded by Remote Configs; use Remote Configs for new integrations. Partial update. Only supplied fields are changed. `product_ids` replaces the full list in the given order — pass `[]` to detach all products, omit the field to leave the list unchanged.



# Create a product
Source: https://documentation.qonversion.io/api-reference/products/create-a-product

/api-reference/rest-api-v4.yaml post /products
Creates a new product for the authenticated project.



# Delete a product
Source: https://documentation.qonversion.io/api-reference/products/delete-a-product

/api-reference/rest-api-v4.yaml delete /products/{product_id}
Deletes a product by ID. Returns 204 on success. Returns 404 if the product does not exist.



# Get a product
Source: https://documentation.qonversion.io/api-reference/products/get-a-product

/api-reference/rest-api-v4.yaml get /products/{product_id}
Returns a single product by ID.



# Get products
Source: https://documentation.qonversion.io/api-reference/products/get-products

/api-reference/rest-api.yaml get /products/{id}
Retrieve a single product by ID, or omit the ID to get all dashboard products.




# List products
Source: https://documentation.qonversion.io/api-reference/products/list-products

/api-reference/rest-api-v4.yaml get /products
Returns a paginated list of products for the authenticated project.
Products are ordered by creation date (newest first).
Manifest-compliant: list envelope, string enums, ISO 8601 timestamps.




# Patch a product
Source: https://documentation.qonversion.io/api-reference/products/patch-a-product

/api-reference/rest-api.yaml patch /products/{uid}
Partially updates a product. Only the submitted fields are updated — omitted fields remain unchanged.




# Update a product
Source: https://documentation.qonversion.io/api-reference/products/update-a-product

/api-reference/rest-api.yaml put /products/{uid}
Replaces all product fields. Unlike PATCH, all fields must be provided — omitted fields are reset to defaults.




# Update a product (partial)
Source: https://documentation.qonversion.io/api-reference/products/update-a-product-partial

/api-reference/rest-api-v4.yaml patch /products/{product_id}



# Get project settings
Source: https://documentation.qonversion.io/api-reference/project-settings/get-project-settings

/api-reference/rest-api-v4.yaml get /project-settings
Returns the settings for the authenticated project, including API keys,
proxy URLs, and project name.




# Get store configuration
Source: https://documentation.qonversion.io/api-reference/project-settings/get-store-configuration

/api-reference/rest-api-v4.yaml get /project-settings/stores/{platform}
Returns the store configuration for the specified platform.
Sensitive fields (private keys, service account credentials) are masked
with boolean flags (has_connect_private_key, has_service_account_key, etc.).




# Regenerate project secret key
Source: https://documentation.qonversion.io/api-reference/project-settings/regenerate-project-secret-key

/api-reference/rest-api-v4.yaml post /project-settings/regenerate-secret
Regenerates the project's secret key. The old key is revoked; clients may see a short grace period (seconds) while internal caches expire.
This is a destructive operation.

Idempotency is intentionally NOT supported: caching a newly generated
secret in a shared replay cache would leak credentials. Each call
produces a fresh secret — clients must treat every request as unique.




# Update project settings
Source: https://documentation.qonversion.io/api-reference/project-settings/update-project-settings

/api-reference/rest-api-v4.yaml patch /project-settings
Partially updates the project settings. Only provided fields are changed.




# Update store configuration
Source: https://documentation.qonversion.io/api-reference/project-settings/update-store-configuration

/api-reference/rest-api-v4.yaml post /project-settings/stores/{platform}
Updates the store configuration for the specified platform.
For Apple: if private keys are not provided, existing values are preserved.
For Google: if service account key is not provided, existing value is preserved.




# Create a purchase
Source: https://documentation.qonversion.io/api-reference/purchases/create-a-purchase

/api-reference/rest-api.yaml post /users/{user_id}/purchases
Records a purchase for a user. Stripe and Paddle are the recommended paths when calling this
API directly; App Store and Play Store purchases normally flow through the Qonversion SDK and
rarely need to be POSTed manually.

Provide exactly one of `stripe_store_data`, `paddle_store_data`, `app_store_data`, or `play_store_data`.


<Note>Stripe and Paddle are the typical use cases. `app_store_data` and `play_store_data` are
accepted for completeness but App Store and Play Store purchases are normally handled
automatically by the Qonversion SDK.</Note>


# List purchases for a user
Source: https://documentation.qonversion.io/api-reference/purchases/list-purchases-for-a-user

/api-reference/rest-api-v4.yaml get /users/{user_id}/purchases
Returns a paginated list of purchases for the specified user.
Purchases are ordered by purchase date (newest first).
Supports cursor-based pagination and optional platform filtering.




# Attach a user to a remote configuration
Source: https://documentation.qonversion.io/api-reference/remote-configurations/attach-a-user-to-a-remote-configuration

/api-reference/rest-api-v4.yaml post /remote-configurations/{config_id}/users/{user_id}
Pins a specific user to this configuration, overriding segment and percentage targeting rules. The pin is never re-evaluated and survives config edits until removed; it also invalidates the SDK's in-memory config cache.



# Change remote configuration status
Source: https://documentation.qonversion.io/api-reference/remote-configurations/change-remote-configuration-status

/api-reference/rest-api-v4.yaml patch /remote-configurations/{config_id}/status
Changes the status of a remote configuration. Allowed transitions: `draft` → `active`, `draft` → `archived`, `active` → `archived`. Archiving is terminal — an archived configuration can only be deleted. Only `active` configurations are served to the SDK.



# Create a remote configuration
Source: https://documentation.qonversion.io/api-reference/remote-configurations/create-a-remote-configuration

/api-reference/rest-api-v4.yaml post /remote-configurations
Creates a new remote configuration. New configurations start in `draft` status. Returns 201 with the created configuration and a Location header.



# Delete a remote configuration
Source: https://documentation.qonversion.io/api-reference/remote-configurations/delete-a-remote-configuration

/api-reference/rest-api-v4.yaml delete /remote-configurations/{config_id}
Deletes a remote configuration by ID. Returns 204 on success.



# Detach a user from a remote configuration
Source: https://documentation.qonversion.io/api-reference/remote-configurations/detach-a-user-from-a-remote-configuration

/api-reference/rest-api-v4.yaml delete /remote-configurations/{config_id}/users/{user_id}
Removes a user's manual pin to this configuration, invalidates the SDK's in-memory config cache, and makes the user eligible for automatic targeting evaluation on the next request.



# Get a remote configuration
Source: https://documentation.qonversion.io/api-reference/remote-configurations/get-a-remote-configuration

/api-reference/rest-api-v4.yaml get /remote-configurations/{config_id}
Returns a single remote configuration by ID, including its read-only inline `payload` values (`{}` when unset).



# Get the payload mapping
Source: https://documentation.qonversion.io/api-reference/remote-configurations/get-the-payload-mapping

/api-reference/rest-api-v4.yaml get /remote-configurations/{config_id}/payload-mapping
Returns the payload **mapping** — the key → type schema that tells the SDK how to interpret each payload key. This is the schema, not the values: see the payload endpoint for the JSON values delivered to the SDK.



# Get the payload values
Source: https://documentation.qonversion.io/api-reference/remote-configurations/get-the-payload-values

/api-reference/rest-api-v4.yaml get /remote-configurations/{config_id}/payload
Returns the payload **values** — the actual JSON object delivered to the SDK for this configuration (`{}` when unset). This is distinct from the payload mapping, which describes the key → type schema.



# List remote configurations
Source: https://documentation.qonversion.io/api-reference/remote-configurations/list-remote-configurations

/api-reference/rest-api-v4.yaml get /remote-configurations
Returns a paginated list of remote configurations for the authenticated project.
Configurations are ordered by creation date (newest first). List items do not include the inline `payload` values — read a single configuration or the payload endpoint to fetch them.




# Replace the payload values
Source: https://documentation.qonversion.io/api-reference/remote-configurations/replace-the-payload-values

/api-reference/rest-api-v4.yaml put /remote-configurations/{config_id}/payload
Replaces the payload **values** delivered to the SDK. Full replace: the supplied `data` object entirely overwrites the stored payload — to change one key, read the current payload, modify it, and send the whole object back. An empty object `{}` clears the payload. Requests are limited to 64 KiB.



# Set the payload mapping
Source: https://documentation.qonversion.io/api-reference/remote-configurations/set-the-payload-mapping

/api-reference/rest-api-v4.yaml post /remote-configurations/{config_id}/payload-mapping
Replaces the payload **mapping** (key → type schema). Full replace: the supplied `data` object becomes the complete mapping. Allowed types: `String`, `Number`, `Bool`, `Json`, `Color`, `Products`, `Screens`.



# Update a remote configuration (full replace)
Source: https://documentation.qonversion.io/api-reference/remote-configurations/update-a-remote-configuration-full-replace

/api-reference/rest-api-v4.yaml put /remote-configurations/{config_id}
Replaces the configuration's editable fields. `name` is required; omitted optional fields are reset. Use the status and payload endpoints to change status or payload values.



# Create scheduled report
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/create-scheduled-report

/api-reference/rest-api-v4.yaml post /scheduled-reports
Creates a new scheduled report.



# Delete scheduled report
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/delete-scheduled-report

/api-reference/rest-api-v4.yaml delete /scheduled-reports/{report_id}
Deletes a scheduled report.



# Get scheduled report
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/get-scheduled-report

/api-reference/rest-api-v4.yaml get /scheduled-reports/{report_id}
Returns details for a single scheduled report.



# List available destinations
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/list-available-destinations

/api-reference/rest-api-v4.yaml get /scheduled-reports/destinations
Returns all available report destinations (email, S3, GCS, etc.).



# List scheduled reports
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/list-scheduled-reports

/api-reference/rest-api-v4.yaml get /scheduled-reports
Returns all scheduled reports for the authenticated project.



# Send test report
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/send-test-report

/api-reference/rest-api-v4.yaml post /scheduled-reports/{report_id}/send-test
Triggers a test send for a scheduled report. Returns 202 Accepted.



# Update scheduled report
Source: https://documentation.qonversion.io/api-reference/scheduled-reports/update-scheduled-report

/api-reference/rest-api-v4.yaml put /scheduled-reports/{report_id}
Partially update a scheduled report. Omit any field to keep its current value; at least one field must be supplied.



# Create a screen
Source: https://documentation.qonversion.io/api-reference/screens/create-a-screen

/api-reference/rest-api-v4.yaml post /screens
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Creates a new screen skeleton for the authenticated project.

The created screen has no visual content yet — it is a placeholder you then open in the Qonversion dashboard to lay out components, upload media, and add localisations. Render-time fields (`background`, `default_lang`, `configs`, `content`, `prod_key`, `sandbox_key`) are populated by the dashboard editor, not by this endpoint.

Returns `201 Created` with the newly created `V4Screen` and a `Location` header pointing at `GET /v4/screens/{screen_id}`.





# Delete a screen
Source: https://documentation.qonversion.io/api-reference/screens/delete-a-screen

/api-reference/rest-api-v4.yaml delete /screens/{screen_id}
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Permanently deletes a screen by ID.



# Duplicate a screen
Source: https://documentation.qonversion.io/api-reference/screens/duplicate-a-screen

/api-reference/rest-api-v4.yaml post /screens/{screen_id}/copy
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Creates a copy (duplicate) of an existing screen.
The duplicated screen is returned with a new `id` and status `draft`.
No request body is required.




# Get a screen
Source: https://documentation.qonversion.io/api-reference/screens/get-a-screen

/api-reference/rest-api-v4.yaml get /screens/{screen_id}
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Returns a single screen by ID.

By default the response is the full `V4Screen`, including the render-time fields (`background`, `default_lang`, `configs`, `content`, `prod_key`, `sandbox_key`, `used`) an SDK needs to display a paywall.

Pass `render=false` to receive the lean `V4ScreenSummary` instead — the same shape returned on `GET /v4/screens`. Useful when you only need metadata and want to avoid fetching the render payload, which can be several kilobytes per screen.




# Get per-screen analytics
Source: https://documentation.qonversion.io/api-reference/screens/get-per-screen-analytics

/api-reference/rest-api-v4.yaml get /screens/{screen_id}/analytics
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Returns analytics metrics for a single screen.
Supports optional time-range, environment, currency, and unit filters.




# Get screens analytics overview
Source: https://documentation.qonversion.io/api-reference/screens/get-screens-analytics-overview

/api-reference/rest-api-v4.yaml get /screens/analytics/overview
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Returns aggregated analytics metrics across all screens for the authenticated project.
Supports optional time-range, environment, currency, and unit filters.




# List screens
Source: https://documentation.qonversion.io/api-reference/screens/list-screens

/api-reference/rest-api-v4.yaml get /screens
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Returns a paginated list of screens for the authenticated project.
Screens are ordered by creation date (newest first) and include every screen visible in the Qonversion dashboard (statuses `draft`, `published`, `modified`, and historical `legacy`).
Supports cursor-based pagination via `limit` and `starting_after`.





# Publish a screen
Source: https://documentation.qonversion.io/api-reference/screens/publish-a-screen

/api-reference/rest-api-v4.yaml post /screens/{screen_id}/publish
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Publishes a screen, setting its status to `published`.
No request body is required.




# Update a screen
Source: https://documentation.qonversion.io/api-reference/screens/update-a-screen

/api-reference/rest-api-v4.yaml put /screens/{screen_id}
Deprecated — the Screens product surface has been removed; this API remains available for existing integrations only. Updates a screen's name. All mutable fields must be provided.



# Create a segment
Source: https://documentation.qonversion.io/api-reference/segments/create-a-segment

/api-reference/rest-api-v4.yaml post /segments
Creates a new segment. Returns 201 with the created segment and Location header.



# Delete a segment
Source: https://documentation.qonversion.io/api-reference/segments/delete-a-segment

/api-reference/rest-api-v4.yaml delete /segments/{segment_id}
Deletes a segment by ID. Returns 204 on success. System segments cannot be deleted (422).



# Get a segment
Source: https://documentation.qonversion.io/api-reference/segments/get-a-segment

/api-reference/rest-api-v4.yaml get /segments/{segment_id}
Returns a single segment by ID.



# List segments
Source: https://documentation.qonversion.io/api-reference/segments/list-segments

/api-reference/rest-api-v4.yaml get /segments
Returns a paginated list of segments for the authenticated project.
Segments are ordered by creation date (newest first).




# List system segments
Source: https://documentation.qonversion.io/api-reference/segments/list-system-segments

/api-reference/rest-api-v4.yaml get /segments/system
Returns all predefined system segments. System segments are read-only
and cannot be modified or deleted.




# Update a segment (full replace)
Source: https://documentation.qonversion.io/api-reference/segments/update-a-segment-full-replace

/api-reference/rest-api-v4.yaml put /segments/{segment_id}
Replaces all fields of a segment. All fields are required.



# Create user properties
Source: https://documentation.qonversion.io/api-reference/user-properties/create-user-properties

/api-reference/rest-api.yaml post /users/{id}/properties
Sets properties for a user. Supports partial success - returns both saved properties and errors.

**Rate limit:** Properties endpoints are rate-limited per project (default 30 requests
per second; configurable on the server). Exceeding the limit returns 429.




# List properties for a user
Source: https://documentation.qonversion.io/api-reference/user-properties/list-properties-for-a-user

/api-reference/rest-api-v4.yaml get /users/{user_id}/properties
Returns all stored properties for the specified user (up to 100 per user).
The response is always a single page — there is no cursor pagination, so
`has_more` is always `false` and `next_cursor` is always `null`.
Qonversion-defined keys are prefixed with `_q_` (e.g., `_q_email`).




# Retrieve user properties
Source: https://documentation.qonversion.io/api-reference/user-properties/retrieve-user-properties

/api-reference/rest-api.yaml get /users/{id}/properties
Retrieves all properties for a given user. Up to 100 properties per user.

**Rate limit:** Properties endpoints are rate-limited per project (default 30 requests
per second; configurable on the server). Exceeding the limit returns 429.


<Note>Qonversion-defined properties are prefixed with `_q_` (e.g. `_q_email`). Custom properties use your own keys.</Note>


# Set (upsert) properties for a user
Source: https://documentation.qonversion.io/api-reference/user-properties/set-upsert-properties-for-a-user

/api-reference/rest-api-v4.yaml post /users/{user_id}/properties
Upserts one or more properties for the specified user (1-100 items per call).
Each property is identified by a key; existing values are overwritten.
Supports partial success: as long as **at least one** property passes
validation, the response is 200 with successfully saved properties under
`saved_properties` and per-key failures under `property_errors`.

**Effective validation** (applied per-item):
- `key` — 1-80 characters, matching `^[-a-zA-Z0-9_.:]+$` and containing
  at least one letter. Keys starting with `_` are reserved for Qonversion
  system properties; only pre-registered keys prefixed with `_q_` (e.g.
  `_q_email`, `_q_name`) are accepted.
- `value` — up to 120 bytes, must not contain `\n`, `\r`, `"`, or `'`.

**400 behaviour** — returned without a per-key breakdown when:
- the request itself is malformed (empty array, more than 100 items, or
  key/value exceeding the gateway's 256/1024-character limits), or
- every property in the request fails validation (there is nothing to
  save). In that case retry with the offending keys removed to see
  per-key reasons in the 200 response.




# Create a user
Source: https://documentation.qonversion.io/api-reference/users/create-a-user

/api-reference/rest-api-v4.yaml post /users
Create a new Qonversion user. The server generates the `QON_…` user id
and returns it in the response body and the `Location` header.

v3's `POST /v3/users/{id}` accepted a client-supplied id; v4
standardises on server-issued ids across every resource.

Pass an `Idempotency-Key` header to make retries safe — the same key
returns the originally-created user instead of creating a duplicate.


<Warning>Use `sandbox` environment for testing. Sandbox users do not affect production analytics.</Warning>


# Get a user
Source: https://documentation.qonversion.io/api-reference/users/get-a-user

/api-reference/rest-api-v4.yaml get /users/{user_id}
Returns a single user by ID.



# Retrieve a user
Source: https://documentation.qonversion.io/api-reference/users/retrieve-a-user

/api-reference/rest-api.yaml get /users/{id}
Retrieves a Qonversion user by their ID.

<Info>User IDs are generated by the Qonversion SDK (prefixed with `QON_`) or set manually via the API.</Info>


# Changelog
Source: https://documentation.qonversion.io/changelog

Latest updates and improvements to the Qonversion platform

<Update label="August 2026" description="Remote Config cache invalidation API">
  ## Remote Config Cache Invalidation API

  New SDK method `invalidateRemoteConfigsCache()` forces the next `remoteConfig` / `remoteConfigList` call to fetch a fresh targeting evaluation instead of serving the in-memory cache — useful right after setting user properties your targeting depends on. Additionally, `identify` now drops the config cache even when the user id doesn't change, so re-login flows always evaluate fresh.

  Available in **iOS 6.14.0**, **Android 9.7.0**, **React Native 10.11.0**, **Flutter 11.10.0**, **Cordova 7.9.0**, **Capacitor 1.8.0**, and **Unity 9.9.0**.

  See [Invalidate the config cache](remote-config#invalidate-the-config-cache) for usage and [When a device fetches a config](remote-config-targeting#when-a-device-fetches-a-config) for the full caching rules.
</Update>

<Update label="August 2026" description="Freeze assignments for Remote Configs">
  ## Freeze Assignments for Remote Configs

  Keep users on the Remote Config they already received — no matter how the targeting changes later. Turn on **Freeze assignments** in the configuration's Targeting card, and every user who newly receives the config is pinned: later targeting-rule, rollout-percentage, or priority changes won't re-seat them. When enabling, you can optionally pin everyone who has already received the config in one shot.

  Payload edits still apply to pinned users, and turning the switch off does not unfreeze anyone — detach users individually or archive/delete the configuration to release them.

  See [Freezing assignments](remote-config-targeting#freezing-assignments) for the exact semantics.
</Update>

<Update label="August 2026" description="Remote Config rollout percentage is now enforced">
  ## Rollout Percentage Is Now Enforced

  The rollout percentage (`segment_percent`) of a Remote Config now actually gates delivery: a user is admitted when their stable per-config bucket falls below the percent. The decision is **deterministic** — a config edit never reshuffles who is inside the rollout, and raising the percent only adds users.

  One heads-up: **drafts saved with a partial rollout come alive on activation.** A draft configured at, say, 43% will gate 43% of matching users the moment you activate it — review the rollout field of your drafts before flipping them on.

  See [How targeting and assignment works](remote-config-targeting) for the full evaluation model.
</Update>

<Update label="July 2026" description="Web Funnel — sell subscriptions on the web (beta)">
  ## Web Funnel

  Sell your subscriptions on the web and unlock them in your app. Build a checkout funnel as a No-Code screen, hosted by Qonversion at `screens.qonversion.io`, let users pay with **Stripe** in the browser (from ads, emails, or influencer links), and have them **redeem** the purchase inside your mobile app — Qonversion grants entitlements and tracks the revenue alongside your App Store and Google Play subscriptions.

  Available now in **beta / early access**, and you can validate the whole flow end to end with **sandbox testing** before going live.

  See the [Web Funnel guide](web-funnel) and [Web Funnel redemption](web-funnel-redemption) to get started.
</Update>

<Update label="July 2026" description="No-Code Builder & SDK updates">
  ## No-Code Builder & SDK Updates

  Several No-Code improvements shipped with **iOS SDK 6.13.0** and **Android No-Codes SDK 1.10.0**:

  * **Custom purchase loader.** Replace the SDK's default purchase spinner with your own — a styled spinner or a **Lottie** animation — configured entirely in the No-Code Builder. See the [Purchase Loader guide](purchase-loader).
  * **Read a screen's configured products and variables.** Load a screen up front with `loadScreen` and read the product IDs and screen variables configured in the Builder — each value keeping its native type — for analytics consistency and app-side logic. See [Reading default variables](displaying-no-codes#reading-default-variables).
  * **Custom actions.** Trigger a custom action from a No-Code screen and handle it in your app through a new delegate event. See [Custom Actions](custom-actions).
  * **No-Codes in Kids Mode.** No-Code screens are now available from the No-IDFA (Kids Mode) Qonversion SDK, starting with **iOS SDK 6.12.1**. See [Kids Mode](kids-mode-sdk).
</Update>

<Update label="June 2026" description="Paddle web payments">
  ## Paddle Integration

  Qonversion now supports [Paddle](paddle-integration) as a web payment provider, alongside the App Store, Google Play, and Stripe. Connect your Paddle account with an API key (Qonversion registers the webhook destination automatically), map your Paddle products, and link purchases to Qonversion users with `custom_data` so entitlements are granted and revenue is tracked from Paddle webhooks.

  See the [Paddle Integration guide](paddle-integration) and [Paddle Credentials](paddle-credentials) to get started.
</Update>

<Update label="April 2026" description="Improved Grace Period Handling for MRR/ARR">
  ## Improved Billing Grace Period Support

  Subscription analytics charts — including MRR, ARR, MRR Movement, ARR Movement, Active Subscriptions, Subscriptions Movement, and Cohorts — now accurately reflect store-configured billing grace periods for both Apple and Google Play subscriptions.

  Qonversion now reads the actual grace period duration from App Store Connect and Google Play Console, ensuring that subscriptions in billing retry are counted as active for the correct duration before being classified as churned. No action is required — the improvement is applied automatically.
</Update>

<Update label="February 2026" description="SDK Updates">
  ## Cordova SDK 7.x and Capacitor SDK 1.x

  New major versions for Cordova and Capacitor SDKs with improved plugin architecture.

  See the [Cordova 7 migration guide](jan-2026-migration-guide-cordova-7) and [Capacitor 1 migration guide](jan-2026-migration-guide-capacitor-1).
</Update>

<Update label="November 2025" description="iOS SDK 6.0">
  ## iOS SDK 6.0

  Major update to the iOS SDK with performance improvements and new APIs.

  See the [iOS 6.0 migration guide](nov-2025-migration-guide-ios-600).
</Update>

<Update label="September 2025" description="React Native SDK 10.x">
  ## React Native SDK 10.x

  Updated React Native SDK with improved TypeScript support and new features.

  See the [React Native 10 migration guide](sep-2025-migration-guide-react-native-10).
</Update>


# Account Overview
Source: https://documentation.qonversion.io/docs/account-overview

A single page that aggregates analytics across all projects in your organization.

<img alt="Account Overview page" />

Account Overview gives you a high-level view of revenue, subscriptions, trials, and users without switching between projects one-by-one.

## Who can use it

Account Overview is available when:

* Your account has **2 or more projects**
* Your role grants the **Access to analytics** permission

If you don't see the option, contact your account Owner or Administrator to request access.

## How to open it

Click the project switcher in the top-left corner of the dashboard. At the bottom of the dropdown you'll see an **Account Overview** button — click it to open the page.

While you're on Account Overview, the project switcher shows **All projects** instead of a single project name, and most sidebar items are disabled. To go back to a single project, pick it from the switcher.

## What's on the page

### Top cards

Five summary cards show totals for the selected period across all your projects:

* **Sales** — gross revenue from purchase events
* **MRR** — monthly recurring revenue (active regular subscriptions)
* **New Trials** — number of trials started
* **New Subscriptions** — number of subscriptions activated
* **Active Subscriptions** — number of currently active subscriptions

Each card shows the current value and the percentage change vs. the previous period.

### Charts

Six time-series charts mirror the cards plus **New Users** (clients created in the period). Hover any chart to see daily values; toggle the legend to focus on specific series.

### Breakdown table (Projects)

When you switch **Group By** away from "Total", a per-project breakdown table appears below the charts. It lists each project with the same metrics, so you can spot which projects drive the totals. Click any row to drill into that project's standard analytics.

## Filters and grouping

The toolbar above the cards offers two controls:

### Group by

Splits charts and the breakdown table by a dimension:

* **Total** — single aggregated series (default)
* **Project** — one series per project
* **Store**, **Country**, **Currency**, **Locale**, **Device**, **OS version**, **SDK version** — split by client property

### Filter

Narrows down the data without changing the grouping. Click **Filter**, pick a dimension (Store, Country, Device, etc.), then choose values. Multiple filters apply together (AND).

Filter values are loaded from data observed across your projects, so what you see depends on what your apps report.

## Date range and currency

* **Date range** — the standard 7d / 30d / 90d / custom controls in the top-right. The previous period (used for the % change indicator) is the same length immediately before the selected range.
* **Currency** — change the display currency from the gear icon (top-right). All revenue values (Sales, MRR) are converted using daily exchange rates.

## Tips

* **Open one project quickly** — click any row in the breakdown table to jump straight to that project's monitoring dashboard.
* **Keep your filters** — date range, group-by, and value filters are preserved in the URL, so you can bookmark or share a specific view.
* **Compare apps** — pick "Group by Project" with a 30-day range to see which apps grew and which declined in the period.
* **Check trial-to-paid health** — combine **New Trials** and **New Subscriptions** charts; a widening gap may indicate trial conversion drops.


# Migrating from Adapty to Qonversion
Source: https://documentation.qonversion.io/docs/adapty-migration-guide

We have prepared this guide to help you move your infrastructure seamlessly from Adapty to Qonversion. Although this guide is comprehensive and should enable you to transfer the entire infrastructure smoothly, feel free to reach out to support if you have any questions.

1. [Configure dashboard](#configure-dashboard)
2. [Install SDKs](#install-sdks)
3. [User-base migration](#user-base-migration)

## Configure dashboard

First and foremost, [register](https://go.qonversion.io/8C4r) at Qonversion. Registration will take you through an onboarding process, where you'll have to fill out information about your project and insert links — all to help you add your project to Qonversion. We highly recommend following this flow and not skipping any settings during registration. We'll also cover the scenario if you don't fill these out.

### Store Settings

First, let's set up your Stores in the Qonversion dashboard. To do this, gather the necessary data from Adapty.

#### Apple App Store settings

To configure the Apple App Store in Qonversion, you will need the following fields:

1. **App-Specific Shared Secret**: Copy this value from the App Store Connect shared secret field in the App Settings -> iOS SDK section in the Adapty dashboard. [Here's](ios-app-store-info-fields#2-generate-the-app-specific-shared-secret) a more detailed guide on how to obtain this.
2. **App Store ID**: You'll find your App Store ID in the URL of your App Store Connect account. For example, if your URL is something like `https://apps.apple.com/us/app/example-app/id123456789`, then 123456789 is your app’s Apple ID.

<img alt="" />

#### Google Play Console Settings

Here's what you have at Adapty:

<img alt="" />

To set up your Google Play account in Qonversion, you will need the following:

1. **Android Package Name**: This is the applicationID found in your app-level build.gradle file. You can either copy it from there or use the **Package Name** from your Adapty settings.
2. **Service Account Credentials JSON**: Copy the value from the **Service account key file** shown in the screenshot above, or attach the same file you used with Adapty. [Here's more](android-store-setup) on how you can get Google Play Service Account Key.

<Check>
  ### Configure Stores in Qonversion

  Once you have all the necessary data from Adapty, follow the steps to fill in the required Stores in Qonversion
</Check>

[Stores Settings](https://demo.arcade.software/Eq6Y1v6okCVCUhOcYfUF?embed\&embed_mobile=inline\&embed_desktop=inline\&show_copy_link=true)

### Products, Entitlements and Remote Configs

After you've filled the store data, it's time to set up Remote Configs, Products, and Entitlements. Here's another way to describe these elements:

| Adapty        | Qonversion     |
| ------------- | -------------- |
| Access levels | Entitlements   |
| Products      | Products       |
| Paywalls      | Remote Configs |

#### Entitlements (Access levels)

Let's start with Entitlements. Similar to how you set up Access levels in Adapty, you need to set up Entitlements in Qonversion.

Here’s how it was done in Adapty:

<img alt="" />

Here’s how to do it in Qonversion:

Navigate to the Entitlements and click the **Create Entitlement** button.

[Create entitlements](https://demo.arcade.software/dYOIEanZRhOmQ9zidazH?embed\&embed_mobile=inline\&embed_desktop=inline\&show_copy_link=true)

#### Products

Next, you need to create Products similar to how you created in Adapty:

<img alt="" />

To create Products in Qonversion, go to **Entitlements → Products** and click **Create Product**.

[Entitlements – Products](https://demo.arcade.software/Evi7fa9nT4xmjzuavh4j?embed\&embed_mobile=inline\&embed_desktop=inline\&show_copy_link=true)

* **Qonversion Product ID** is your unique product identifier in Qonversion that corresponds to a unique product on the Apple App Store and Google Play Store. Qonversion SDK will use it to make purchases.

* **AppStore Product ID** – product identifier on Apple App Store. Learn more on how to create [subscriptions on iOS](https://qonversion.io/blog/configure-iap-app-store-connect/).

* **Google Play Product ID** – product identifier on Google Play Console. Learn more on how to set up [Android in-app products ](android-in-app-products).

* **Google Play Base Plan ID** - identifier of the base plan for Google Play Product. This is used for subscription products. If you're creating an in-app, leave this field empty for in-apps. In Qonversion, you will set up different products for the different base plans of the same product.

* **Associated Entitlements** - choose the entitlements that should be granted once this product is purchased.

#### Remote Configs (instead of Adapty Paywalls)

In Adapty, paywalls define which products are presented to the user. In Qonversion, this is covered by [Remote Configs](remote-config): create a configuration with a context key (e.g. `main_paywall`) and put your product IDs into the JSON payload in the order you want to display them:

```json theme={null}
{
  "products": ["weekly_premium", "annual_premium_trial"]
}
```

<Frame>
  <img />
</Frame>

Beyond changing products without an app release, Remote Configs also let you [target user segments](remote-config#5-segment-users) and [run A/B tests](launch-test-from-remote-config). See [the payload convention and code samples](migrate-offerings-to-remote-configs) for details.

### Server-to-server notifications

To seamlessly implement server-to-server notifications, use Adapty S2S URLs as a temporary proxy in our system. This allows Qonversion to process new requests while still sending notifications to your existing users.

#### Configure Apple App Store

1. Navigate to your Qonversion [project settings](https://dash.qonversion.io/project-settings/stores?tab=ios). Copy the server-to-server notification URL for Apple App Store.
2. Sign in to [App Store Connect](https://appstoreconnect.apple.com/apps) and select your app.
3. Navigate to the App Information section.

<img alt="" />

4. Copy the Adapty URL you used for server-to-server notifications and replace it with the URL from step 1.
5. Set up the Adapty URL as a Proxy URL in Qonversion in [project settings](https://dash.qonversion.io/project-settings/stores?tab=ios).

See more information [here](ios-s2s-notifications).

#### Google Developer Notifications

1. [Enable access to API here](https://console.cloud.google.com/flows/enableapi?apiid=pubsub).

   <img alt="" />

2. Navigate to [project settings](https://dash.qonversion.io/project-settings/stores?tab=android), then click the "Connect to Google" button.

3. You need to copy generated **Google Developer Notifications Topic ID**.

4. Open the **Google Play Console** for your application, then navigate to **Monetization setup**.

5. In the **Real-time developer notifications** tab, insert your topic ID, click on **Save changes**, and then the **Send Test Notification** button.

It takes up to 24 hours for your [Google service credentials](android-store-setup) to work correctly. Make sure to wait for at least 24 hours after you have created the credentials before connecting to Google Real-Time Developer Notifications.

See more information [here](google-developer-notifications).

## Install SDKs

Check out the links below for the SDK you need and follow the steps provided:

→ [iOS SDK](ios-sdk-setup) → [Android SDK](android-sdk) → [Flutter SDK](flutter-sdk) → [React Native SDK](react-native-sdk) → [Unity SDK](unity-sdk) → [Cordova Plugin](cordova) → [Capacitor Plugin](capacitor) → [Web](web-sdk) → [Kids Mode Qonversion SDKs](kids-mode-sdk)

Read more about [Installing the SDKs](install-sdk).

When you're done with the setup, it's time to get into the code!

### Launch SDK

Firstly, you need to initialize the SDK. Here's how you did it in Adapty:

<CodeGroup>
  ```swift Swift theme={null}
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    let configurationBuilder =
  	Adapty.Configuration
  		.Builder(withAPIKey: "PUBLIC_SDK_KEY")
  		.with(observerMode: false)

  	Adapty.activate(with: configurationBuilder) { error in
    	// handle the error
  	}
  }
  ```

  ```java Java theme={null}
  public class App extends Application {
    @Override
    public void onCreate() {
      super.onCreate()
      Adapty.activate(
        applicationContext,
        new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
      	  .withObserverMode(false)
      	  .build()
      );
    }
  }
  ```

  ```kotlin Kotlin theme={null}
  class App : Application() {
    override fun onCreate() {
      super.onCreate()
      Adapty.activate(
        applicationContext,
        AdaptyConfig.Builder("PUBLIC_SDK_KEY")
      	  .withObserverMode(false)
      	  .build()
    }
  }
  ```

  ```dart Flutter theme={null}
  // Few different steps with iOS Info.plist and AndroidManifest.xml files. 
  // That can be removed while migrating to Qonversion.
  // And then call:
  try {
  	Adapty().activate();
  } on AdaptyError catch (adaptyError) {}
  } catch (e) {}
  ```

  ```typescript React Native theme={null}
  adapty.activate('PUBLIC_SDK_KEY', {
    observerMode: false
  });
  ```

  ```csharp Unity theme={null}
  // Few different steps with iOS Info.plist and AndroidManifest.xml files. 
  // Create a script which will be responsible for listening of Adapty events.
  // Few other steps
  ```
</CodeGroup>

Here's how you'll do it for Qonversion — request the Remote Config holding your product IDs, then resolve them to store products:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig(contextKey: "main_paywall") { remoteConfig, error in
      guard let payload = remoteConfig?.payload,
            let productIds = payload["products"] as? [String] else { return }

      Qonversion.shared().products { allProducts, error in
          let paywallProducts = productIds.compactMap { allProducts[$0] }
          // Display paywallProducts in the configured order
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig("main_paywall", object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          val productIds = (remoteConfig.payload["products"] as? List<*>)
              ?.filterIsInstance<String>() ?: return

          Qonversion.shared.products(object : QonversionProductsCallback {
              override fun onSuccess(products: Map<String, QProduct>) {
                  val paywallProducts = productIds.mapNotNull { products[it] }
                  // Display paywallProducts in the configured order
              }

              override fun onError(error: QonversionError) { /* handle error */ }
          })
      }

      override fun onError(error: QonversionError) { /* handle error */ }
  })
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: 'main_paywall');
  final productIds = List<String>.from(remoteConfig.payload['products'] as List);

  final products = await Qonversion.getSharedInstance().products();
  final paywallProducts = productIds
      .map((id) => products[id])
      .whereType<QProduct>()
      .toList();
  // Display paywallProducts in the configured order
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('main_paywall');
  const productIds: string[] = remoteConfig.payload['products'] ?? [];

  const products = await Qonversion.getSharedInstance().products();
  const paywallProducts = productIds
    .map((id) => products.get(id))
    .filter((product) => product != null);
  // Display paywallProducts in the configured order
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig("main_paywall", (remoteConfig, error) =>
  {
      if (error != null) return;
      var productIds = remoteConfig.Payload["products"] as List<object>;

      Qonversion.GetSharedInstance().Products((products, productsError) =>
      {
          if (productsError != null) return;
          // Pick products by the IDs from the payload and display them
      });
  });
  ```
</CodeGroup>

[See the full guide: products via Remote Configs](migrate-offerings-to-remote-configs)

### Making purchases

Adapty:

<CodeGroup>
  ```swift Swift theme={null}
  Adapty.makePurchase(product: product) { result in
      switch result {
      case let .success(info):
        if info.profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive ?? false {
          // successful purchase
        }
      case let .failure(error):
          // handle the error
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  Adapty.makePurchase(activity, product) { result ->
      when (result) {
          is AdaptyResult.Success -> {
              val info = result.value
              //NOTE: info is null in case of cross-grade with DEFERRED proration mode
              val profile = info?.profile
          
              if (profile?.accessLevels?.get("YOUR_ACCESS_LEVEL")?.isActive == true) {
                  // grant access to premium features
              }
          }
          is AdaptyResult.Error -> {
              val error = result.error
              // handle the error
          }
      }
  }
  ```

  ```java Java theme={null}
  Adapty.makePurchase(activity, product, result -> {
      if (result instanceof AdaptyResult.Success) {
          AdaptyPurchasedInfo info = ((AdaptyResult.Success<AdaptyPurchasedInfo>) result).getValue();
          //NOTE: info is null in case of cross-grade with DEFERRED proration mode
          AdaptyProfile profile = info != null ? info.getProfile() : null;
          
        	if (profile != null) {
              AdaptyProfile.AccessLevel premium = profile.getAccessLevels().get("YOUR_ACCESS_LEVEL");
              
            	if (premium != null && premium.isActive()) {
                  // successful purchase
              }
          }
      } else if (result instanceof AdaptyResult.Error) {
          AdaptyError error = ((AdaptyResult.Error) result).getError();
          // handle the error
      }
  });
  ```

  ```dart Flutter theme={null}
  try {
    final profile = await Adapty().makePurchase(product: product);
    if (profile?.accessLevels['YOUR_ACCESS_LEVEL']?.isActive ?? false) {
  		// successful purchase      
    }
  } on AdaptyError catch (adaptyError) {
  	// handle the error
  } catch (e) {
  }
  ```

  ```csharp Unity theme={null}
  Adapty.MakePurchase(product, (profile, error) => {
    if(error != null) {
        // handle error
        return;
    }
    
    var accessLevel = profile.AccessLevels["YOUR_ACCESS_LEVEL"];
    if (accessLevel != null && accessLevel.IsActive) {
        // grant access to features
    }
  });
  ```

  ```typescript React Native (TS) theme={null}
  try {
  	const profile = await adapty.makePurchase(product);
    const isSubscribed = profile?.accessLevels['YOUR_ACCESS_LEVEL']?.isActive;
    
  	if (isSubscribed) {
  		// grant access to features in accordance with access level
  	}
  } catch (error) {
  	// handle the error
  }
  ```
</CodeGroup>

Qonversion:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().purchase(product) { (result) in
    if result.isSuccessful {
      if let premium: Qonversion.Entitlement = result.entitlements["premium"], premium.isActive {
        // Grant user access to premium features
      }
    } else if result.isCanceledByUser {
      // Handle canceled purchase
    } else if result.isPending {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
    if (result.isSuccessful) {
      QONEntitlement *premiumEntitlement = result.entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        // Grant user access to premium features
      }
    } else if (result.isCanceledByUser) {
      // Handle canceled purchase
    } else if (result.isPending) {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().purchase(this, product, new QonversionPurchaseCallback() {
      @Override
      public void onResult(@NonNull QPurchaseResult result) {
          if (result.isSuccessful()) {
              QEntitlement premium = result.getEntitlements().get("premium");
              if (premium != null && premium.isActive()) {
                  // Grant user access to premium features
              }
          } else if (result.isCanceledByUser()) {
              // Handle canceled purchase
          } else if (result.isPending()) {
              // Handle pending purchase
          } else {
              // Handle errors
          }
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.purchase(this, product, object : QonversionPurchaseCallback {
      override fun onResult(result: QPurchaseResult) {
          when {
              result.isSuccessful -> {
                  val premium = result.entitlements["premium"]
                  if (premium != null && premium.isActive) {
                      // Grant user access to premium features
                  }
              }
              result.isCanceledByUser -> {
                  // Handle canceled purchase
              }
              result.isPending -> {
                  // Handle pending purchase
              }
              else -> {
                  // Handle errors
              }
          }
      }
  })
  ```

  ```dart Flutter theme={null}
  final result = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    final premium = result.entitlements?['premium'];
    if (premium != null && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript React Native theme={null}
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Purchase(product, (result) =>
  {
      if (result.IsSuccess)
      {
          if (result.Entitlements != null && 
              result.Entitlements.TryGetValue("premium", out var premium) && 
              premium.IsActive)
          {
              // Grant user access to premium features
          }
      }
      else if (result.IsCanceled)
      {
          // Handle canceled purchase
      }
      else if (result.IsPending)
      {
          // Handle pending purchase
      }
      else
      {
          // Handle errors
      }
  });
  ```

  ```typescript Cordova theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript Capacitor theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```
</CodeGroup>

### Restore purchases

If your app has a restore purchases feature on paywalls, just use the Qonversion `restore()` function when users want to restore their purchases.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().restore { [weak self] (entitlements, error) in
    if let error = error {
      // Handle error
    }
    
    if let entitlement: Qonversion.Entitlement = entitlements["plus"], entitlement.isActive {
      // Restored and entitlement is active 
    }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] restore:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull result, NSError * _Nullable error) {
    if (error) {
      // Handle error
    }
    QONEntitlement *entitlement = result[@"active"];
    if (entitlement && entitlement.isActive) {
      // Restored and entitlement is active
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().restore(new QonversionEntitlementsCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
          QEntitlement premiumEntitlement = entitlements.get("premium");

          if (premiumEntitlement != null && premiumEntitlement.isActive()) {
              // handle active entitlement here
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.restore(object : QonversionEntitlementsCallback {
      override fun onSuccess(entitlements: Map<String, QEntitlement>) {
          val premiumEntitlement = entitlements["premium"]
          if (premiumEntitlement != null && premiumEntitlement.isActive) {
              // handle active entitlement here
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().restore();
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
    const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().restore();
   } catch (e) {
    console.log(e);
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Restore((entitlements, error) =>
  {
        if (error == null)
        {
           // Handle entitlements here
        }
        else
        {
          // Handle the error  
          Debug.Log("Error" + error.ToString());
        }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await Qonversion.getSharedInstance().restore();
  } catch (e) {
      console.log(e);
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().restore();
   } catch (e) {
    console.log(e);
  }
  ```
</CodeGroup>

### User status

To check the customer status in Qonversion, you need to use Entitlements. In Adapty, you used profile and access levels.

Adapty:

<CodeGroup>
  ```swift Swift theme={null}
  Adapty.getProfile { result in
      if let profile = try? result.get() {
          // check the access
        	profile.accessLevels["YOUR_ACCESS_LEVEL"]?.isActive ?? false {
          	// grant access to premium features
          }
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  Adapty.getProfile { result ->
      when (result) {
          is AdaptyResult.Success -> {
              val profile = result.value
              // check the access
          }
          is AdaptyResult.Error -> {
              val error = result.error
              // handle the error
          }
      }
  }
  ```

  ```java Java theme={null}
  Adapty.getProfile(result -> {
      if (result instanceof AdaptyResult.Success) {
          AdaptyProfile profile = ((AdaptyResult.Success<AdaptyProfile>) result).getValue();
          // check the access
        
      } else if (result instanceof AdaptyResult.Error) {
          AdaptyError error = ((AdaptyResult.Error) result).getError();
          // handle the error
      }
  });
  ```

  ```dart Flutter theme={null}
  try {
    final profile = await Adapty().getProfile();
    // check the access
  } on AdaptyError catch (adaptyError) {
    // handle the error
  } catch (e) {
  }
  ```

  ```csharp Unity theme={null}
  Adapty.GetProfile((profile, error) => {
    if (error != null) {
      // handle the error
      return;
    }
    
    // check the access
  });
  ```

  ```typescript React Native (TS) theme={null}
  try {
  	const profile = await adapty.getProfile();
  } catch (error) {
    // handle the error
  }
  ```
</CodeGroup>

Qonversion:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().checkEntitlements { (entitlements, error) in
    if let error = error {
      // handle error
      return
    }
    
    if let premium: Qonversion.Entitlement = entitlements["premium"], premium.isActive {
      // unlock feature
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] checkEntitlements:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull entitlements,
                                  NSError * _Nullable error) {
      QONEntitlement *premiumEntitlement = entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        // unlock feature
      }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().checkEntitlements(new QonversionEntitlementsCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
          final QEntitlement premiumEntitlement = entitlements.get("premium");

          if (premiumEntitlement != null && premiumEntitlement.isActive()) {
              // unlock feature
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.checkEntitlements(object: QonversionEntitlementsCallback {
      override fun onSuccess(entitlements: Map<String, QEntitlement>) {
          val premiumEntitlement = entitlements["premium"]
          if (premiumEntitlement != null && premiumEntitlement.isActive) {
              // unlock feature
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().checkEntitlements();
    final premium = entitlements['premium'];
    if (premium != null && premium.isActive) {
      // unlock feature
    }
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
      // unlock feature
    }
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
  {
      if (error == null)
      {
          if (entitlements.TryGetValue("premium", out Entitlement premium) && premium.IsActive)
          {
              // unlock feature
          }
      }
      else
      {
          // Handle the error  
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

      const premiumEntitlement = entitlements.get('premium');
      if (premiumEntitlement != null) {
          // unlock feature
      }
  } catch (e) {
      // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
      // unlock feature
    }
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

### Authorization system

<Info>
  ### Cross-device and cross-platform access

  Set up this section only if you need cross-device and cross-platform access and your project includes an authorization system.
</Info>

Qonversion lets you identify your signed-in users and unlock premium access across multiple devices. Use the `identify()` method to link a user to your signed-in subscriber. Call this method every time you want to use User Identity. For example, when a user logs in. User Identity provides a convenient way of managing premium access of your existing subscribers, including the following cases:

* A user reinstalls your app for any reason. Using the same User ID allows you to provide premium access linked to previously purchased products.
* A user logs in on several devices. You can provide premium access based on a subscription purchased on one of his devices.
* A user logs in on iOS and Android versions of your app. You can provide premium access based on a subscription purchased on one of the platforms.

#### Logging in

When a user logs into his account, call `identify()`.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.shared().identify("your_custom_user_id") { user, error in
    // use user if necessary
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] identify:@"your_custom_user_id"];

  // or the following option, if you want to get notified about the result.

  [[Qonversion sharedInstance] identify:@"your_custom_user_id" completion:^(QONUser * _Nullable user, NSError * _Nullable error) {
    // use user if necessary
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().identify("your_custom_user_id");

  // or the following option, if you want to get notified about the result.

  Qonversion.getSharedInstance().identify("your_custom_user_id", new QonversionUserCallback() {
      @Override
      public void onSuccess(@NonNull QUser user) {
          // use user if necessary
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.shared.identify("your_custom_user_id", object : QonversionUserCallback {
      override fun onSuccess(user: QUser) {
          // use user if necessary
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final userInfo = await Qonversion.getSharedInstance().identify("your_custom_user_id");
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript React Native theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.GetSharedInstance().Identify("your_custom_user_id", (userInfo, error) =>
  {
      if (error == null)
      {
          // use userInfo if necessary
      }
      else
      {
          // Handle the error  
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```bash curl theme={null}
  curl --location --request POST 'https://api.qonversion.io/v3/identities/new_identities_user' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "user_id": "QON_38a2d811afd54a433587620f8696266e"
  }'

  {
      "id": "new_identities_user",
      "user_id": "QON_38a2d811afd54a433587620f8696266e"
  }
  ```
</CodeGroup>

<Warning>
  ### Use the unique user ID stored in your database

  Always use unique user ID values. Otherwise, a user can get matched to another user's entitlements status.
</Warning>

To check entitlements for identified users, you can call the `checkEntitlements` function, which we discussed above.

#### Logging out

You need to call the `logout()` method to handle entitlements for an unauthorized user. Call this method when a user logs out within your app:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().logout()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] logout];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.logout()
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Logout();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().logout();
  ```
</CodeGroup>

When a user logs back into his account, don't forget to use `identify()` method again.

## User-base migration

Those steps have to be done to keep the system working smoothly for your current user base. The necessity of steps depends on the complexity of your system. The simplest system is represented by a single platform infrastructure (Apple, Google, or Stripe). The complex one includes a few platforms with authorization system, your backend infrastructure, and WebHooks handler.

<Warning>
  ### Qonversion Android SDK 9.+ limitation

  For Qonversion Android SDK 9.+, the method `syncHistoricalData()` has been removed because of a limitation in Google Play Billing Library 8, which prevents the retrieval of historical purchases
</Warning>

### Client-side migration

Follow these steps to sync user status and retrieve the latest data from Google and Apple on your current device. Call the `syncHistoricalData()` method right after Qonversion SDK initialization to synchronize all the device-related data and ensure that none of the entitlements has been missed.

### User-database migration

Once you have the app version with Qonversion SDK up and running, it's time to proceed to the server-side migration.

1. Prepare files with [AppStore with Base64 encoded receipt data](migrating-subscriptions#app-store-data-migration-file) or [Google Play with purchase tokens](migrating-subscriptions#google-play-data-migration-file). If you do not have receipt data or purchase tokens on your side but are already running your subscription management with a third-party vendor, you should ask the vendor’s support team for the required data file.
2. Then simply **share the files with us** using our support chat and provide CSV files.

## Release

After finishing all the steps, you're ready to release your app. For complex systems with cross-platform access and authorization setups, make sure your Qonversion team has verified the user database migration.

<Check>
  ### You're good to go

  Check out the detailed Adapty and Qonversion [feature comparison](https://qonversion.io/adapty-alternative) and don't hesitate to contact us if you have questions.
</Check>

***

[Migrating from RevenueCat](migrating-from-revenuecat-to-qonversion)

[Users and Access](users-and-access)


# Adjust
Source: https://documentation.qonversion.io/docs/adjust

Send iOS and Android in-app subscription events to Adjust with Qonversion

Qonversion sends subscription data for iOS and Android apps to your Adjust account to help you understand your marketing performance. Measure what drives your revenue by tracking trial-to-paying-user conversion, subscription renewals, billing retry state, cancellations, refunds, and other useful subscription events. [Here](integrations-overview) you can find the full list of the events tracked.

## 1. Setup the SDKs

1. Make sure you have Adjust SDK installed. More about the Adjust SDK read [here](https://help.adjust.com/en/developer).

2. Set Qonversion SDKs following [Installing the SDKs](install-sdk) guides.

3. Provide to Qonversion Adjust Advertising ID through [User Properties](user-properties#open-links-in-new-tab):

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.adjustAdID, value: Adjust.adid)
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyAdjustAdID value:[Adjust adid]];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.AdjustAdId, Adjust.getAdid());
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.AdjustAdId, Adjust.getAdid())
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.adjustAdId, 'your adjust ad id');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.ADJUST_AD_ID, 'your adjust ad id');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.AdjustAdId, "your adjust ad id");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.ADJUST_AD_ID, 'your adjust ad id');
  ```
</CodeGroup>

<Warning>
  ### Do not track purchase events on the client-side

  Qonversion tracks and sends revenue events, so if you track revenue events with Adjust SDK as well, you may double count the revenue in your Adjust account.
</Warning>

## 2. Configure the Adjust Integration

## Provide Adjust App Token

1. Navigate to the integrations page in Qonversion and select [Adjust ](https://dash.qonversion.io/app/integration/create?name=adjust).
2. Create Adjust token following [this guide](https://help.adjust.com/en/article/server-to-server-events#set-up-s2s-security) and provide your Adjust App Token to Qonversion.

<img alt="" />

## Provide OAuth token (Optional)

If you've [turned on S2S authentication](https://help.adjust.com/en/article/server-to-server-s2s-security) via OAuth token, add the OAuth token.

<img alt="" />

## 3. Configure the event mapping

Navigate to your app in Adjust, select **All Settings** → **Events**, and create events. Provide generated unique event tokens to Qonversion.

<Warning>
  ### Attention

  You must change default Qonversion event names for Adjust integration to the appropriate Adjust event tokens which have been set in the Adjust dashboard. Only events which are mapped to Adjust event tokens will be received by Adjust.
</Warning>

Adjust API doesn't support negative revenue values. All values are sent with a positive sign for this integration, including refunds. To switch off sending revenue value for refunds select Subscription Refunded event from the table of the events and click More Options below.

Please note that you can expect to have server-side events sent to Adjust account for users who installed the app with Qonversion SDK integrated. Qonversion can't get the data on users who subscribed earlier and never opened the app with Qonversion SDK installed.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Adjust account.
</Check>

## Event Payload

In case you need details about data sent to Adjust, follow the example below:

Top-level keys carry the Adjust-required envelope; user-scoped fields (`product_id`, `user_id`, `custom_user_id`, `storefront`) are JSON-encoded into the `partner_parameters` and `partner_params` strings (Adjust accepts both names). Device identifiers are platform-dependent: iOS sends `idfa` + `idfv`, Android sends `gps_adid` + `android_id`.

<CodeGroup>
  ```json iOS theme={null}
  {
    "app_token": "",
    "event_token": "",
    "s2s": 1,
    "created_at_unix": 1640912133,
    "partner_parameters": "{\"product_id\":\"\",\"user_id\":\"QON_...\",\"custom_user_id\":\"\",\"storefront\":\"USA\"}",
    "partner_params":     "{\"product_id\":\"\",\"user_id\":\"QON_...\",\"custom_user_id\":\"\",\"storefront\":\"USA\"}",
    "adid": "00000000000000000000000000000000",
    "idfa": "00000000-0000-0000-0000-000000000000",
    "idfv": "00000000-0000-0000-0000-000000000000",
    "currency": "USD",
    "revenue": 34.511
  }
  ```

  ```json Android theme={null}
  {
    "app_token": "",
    "event_token": "",
    "s2s": 1,
    "created_at_unix": 1640912133,
    "partner_parameters": "{\"product_id\":\"\",\"user_id\":\"QON_...\",\"custom_user_id\":\"\",\"storefront\":null}",
    "partner_params":     "{\"product_id\":\"\",\"user_id\":\"QON_...\",\"custom_user_id\":\"\",\"storefront\":null}",
    "adid": "00000000000000000000000000000000",
    "gps_adid": "00000000-0000-0000-0000-000000000000",
    "android_id": "0000000000000000",
    "currency": "USD",
    "revenue": 34.511
  }
  ```
</CodeGroup>

***

What’s Next

* [Amplitude](amplitude)
* [User Identifiers](user-identifiers)


# AI Image Generation
Source: https://documentation.qonversion.io/docs/ai-image-generation

Just describe what you want, choose a style, and let the AI handle the rest.

Create beautiful, on-brand visuals for your paywalls and onboarding screens — without leaving the Builder and without opening a design tool. Whether you need a quick background, a polished hero image, or a few variations to A/B test, the AI generator gives you fast, flexible options right inside your workflow.

***

Generate high-quality visuals directly inside the Builder using text prompts.

**What you can use it for**

* Abstract gradients and brand backgrounds
* Hero visuals for paywalls
* Illustrations for onboarding steps
* Simple icons or decorative elements
* Quick concept sketches before you commit to a final asset

Generated images appear in your **Gallery** and can be added to Canvas, or deleted at any time.

***

## Available Models

Choose the model that best fits your workflow. Some are optimized for speed, others for final quality.

| **Model Name**   | **Speed**       | **Quality** | **Best For**                                                          |
| ---------------- | --------------- | ----------- | --------------------------------------------------------------------- |
| **Flux Schnell** | ⚡ Fast (\~5s)   | Good        | Quick iterations, previews, early concept exploration                 |
| **Flux Pro**     | 🐢 Slow (\~15s) | Excellent   | Final assets, high-detail visuals, A/B test creatives                 |
| **Nano Banana**  | ⚡ Fast (\~5s)   | Excellent   | High-quality images with fast turnaround; great general-purpose model |

### Model recommendations

* **Flux Schnell** — perfect for exploration. Use it when you want to try multiple prompts quickly.
* **Nano Banana** — best all-around balance of speed and quality.
* **Flux Pro** — use when you’re ready to produce final paywall or onboarding visuals.

***

## How to generate your first image

1. Add **Image Component** to Canvas **Assets** → **AI Image Generation**.
2. Describe what you want.

* Example: “Abstract pastel gradient with soft light, premium feel.”

3. Choose a model .
4. Click Generate.
5. Add Generated Image to your Screen

***

## Prompt tips (that actually help)

Great results don’t require long descriptions. Keep things short and visual:

* Mention a style: “minimal”, “premium”, “flat illustration”, “soft gradient”.
* Mention a mood: “calm”, “playful”, “energetic”.
* Mention colors: “lavender + teal”, “black + neon purple”.
* For paywalls: “clean background, no text”.
* For onboarding: “centered composition”.

**Examples you can paste:**

* “Minimal abstract gradient, violet and deep blue, subtle glow, soft shapes.”
* “Cute playful illustration of a smartphone, bright pastel palette.”
* “Premium wave background, glassy texture, purple tones.”

***

## Daily quota

To keep performance stable, there’s a simple project-wide limit:

* 10 generations **per project** per day
* Resets at 00:00 UTC

Your remaining quota is shown next to the Generator. When it reaches zero, the UI clearly indicates that you’re out, and it reactivates automatically after the reset.

***

[Awards](awards)

[Properties Reference](properties-reference)


# Localization
Source: https://documentation.qonversion.io/docs/ai-localization

Translate all text in your No-Code screens into multiple languages, manually or with AI.

You can localize all text used in your No-Code screens directly in the Builder.

Localization supports manual translation, AI-assisted translation, variables, and live preview, allowing you to create consistent experiences across all languages your app supports.

Once localized, **screens automatically display the correct language** based on the user’s **device locale**. If a translation is missing, the **default language** is used as a **fallback.**

<Warning>
  **Beta Notice**: AI Localization is currently in beta. While it provides fast, high-quality translations for many languages, some results may require manual review — especially for right-to-left (RTL) languages or languages with more complex grammatical structures. We recommend checking all AI-generated translations in the Preview Panel before publishing your screen
</Warning>

***

## Opening the Localization Panel

Open localization by selecting the **Localization** button in the Builder toolbar.

This opens the **Localization Panel**, where you can view all languages, add new ones, translate content, and preview the results in real time.

Your default language appears first and cannot be removed. This is the fallback language for any untranslated content.

<img alt="" />

***

## Adding & Removing Languages

To add additional languages:

1. Open the **Localization Panel.**
2. Select **Add Language.**
3. Choose **one or more** languages from the list. Languages appear using both their display name and ISO code, for example: **French (Belgium) — fr-BE**.

To remove a language, click the ellipsis menu (⋯).

<Warning>
  Removing a language deletes all translations associated with that language.
</Warning>

<img alt="" />

***

## Editing Translations

**The Localization Panel** displays a table of every text element used in your screen.

* Each row represents a text key, and each column represents a language.
* Select any cell to enter a translation. Changes are saved automatically.

<img alt="" />

### Variables

Text fields that include variables such as `{{price}}`, `{{trial_days}}`, or product attributes can be translated normally.

A variable picker is available when editing, allowing you to insert supported variables directly into the translation. Variables cannot be edited or renamed, but they can appear anywhere in your translated text.

<img alt="" />

***

## Using AI Translation

**AI Translation** helps translate content quickly without requiring custom prompts.

AI Translation becomes available when your project includes at least two languages.

You can translate:

* A single language
* Multiple selected languages
* All languages at once

<Info>
  If a translation already exists, the system will ask you whether AI should **overwrite it.**
</Info>

During translation, progress indicators appear in the panel. If an error occurs, you can retry the translation.

**AI-generated translations can be edited manually at any time**.

<img alt="" />

***

## Previewing Localized Screens

The Preview Panel shows your screen rendered in the currently selected language.

**This helps you verify:**

* Line breaks
* Layout shifts
* Text length differences
* Variable placement

You can switch between languages and pages using dropdown selectors.

Variables appear with sample values (e.g., `{{price}}` → \$9.99) so you can check formatting.

The preview updates automatically whenever you change your translations.

<img alt="" />

***

## Fallback Behavior

If a translation **is missing**, the screen uses the **default language** for that text.

This ensures your screens always render fully, even if some translations are incomplete.

***

## Autosave

All translations are saved **automatically** every five seconds. You can exit the localization view at any time, and your changes will persist.

***

## Import & Export

You can import and export all localization data as a JSON file. This is useful for:

* Bulk editing translations in external tools (spreadsheets, translation management systems)
* Backing up localization before major changes
* Sharing translations between team members

### Exporting Translations

1. Open the **Localization Panel**.
2. Click the **Import/Export** button in the header.
3. Select **Export**.
4. A JSON file will download with all your translations.

The exported file includes:

* Screen metadata (ID, name, export date)
* All configured languages
* All texts grouped by pages

![](https://files.readme.io/placeholder-export.png)

### Importing Translations

1. Open the **Localization Panel**.
2. Click the **Import/Export** button.
3. Select **Import**.
4. Choose a JSON file from your device.

**Import behavior:**

* **Screen validation**: The file's `screenId` must match the current screen.
* **Language handling**: New languages in the file are automatically added. Existing translations are overwritten.
* **Default language**: If the file specifies a different default language, it becomes the new default for the screen.

<Warning>
  Import will fail if the file contains language codes not supported by the system, or if the `screenId` doesn't match the current screen.
</Warning>

### JSON Format

The export file uses the following structure:

<CodeGroup>
  ```bash bash theme={null}
  {
    "screenId": "abc123",
    "screenName": "My Paywall",
    "exportedAt": "2026-01-30T12:00:00.000Z",
    "defaultLanguage": "en-US",
    "languages": ["en-US", "de-DE", "fr-FR"],
    "pages": [
      {
        "id": "page-1",
        "name": "Main Page",
        "texts": [
          {
            "id": "text-1",
            "en-US": "Subscribe Now",
            "de-DE": "Jetzt abonnieren",
            "fr-FR": "S'abonner maintenant"
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

| Field             | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `screenId`        | Unique identifier of the screen. Must match when importing. |
| `screenName`      | Display name of the screen (informational only).            |
| `exportedAt`      | ISO 8601 timestamp of the export.                           |
| `defaultLanguage` | Language code for the default/fallback language.            |
| `languages`       | Array of all language codes in the file.                    |
| `pages`           | Array of pages, each containing an array of texts.          |

***

## Passing custom locale to the SDKs

By default, No-Code screens automatically detect the device's system language and display the appropriate localization if available. You can override this behavior by setting a custom locale, which takes priority over the automatic system language detection.

The locale should be in standard format (e.g., `"en"`, `"en-US"`, `"de"`, `"de-DE"`). Pass `nil`/`null` to reset to the system default locale.

**Setting locale during initialization:**

<CodeGroup>
  ```bash bash theme={null}
  var config = NoCodesConfiguration(
      projectKey: "projectKey",
      locale: "de-DE"
  )
  NoCodes.initialize(with: config)
  ```

  ```bash bash theme={null}
  val config = NoCodesConfig.Builder(context, "projectKey")
      .setLocale("de-DE")
      .build()
  NoCodes.initialize(config)
  ```

  ```bash bash theme={null}
  NoCodesConfig config = new NoCodesConfig.Builder(context, "projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(config);
  ```

  ```bash bash theme={null}
  const noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```bash bash theme={null}
  final noCodesConfig = NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```bash bash theme={null}
  var noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .SetLocale("de-DE")
      .Build();
  NoCodes.Initialize(noCodesConfig);
  ```

  ```bash bash theme={null}
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  Qonversion.NoCodes.initialize(noCodesConfig);
  ```

  ```bash bash theme={null}
  const noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(noCodesConfig);
  ```
</CodeGroup>

**Setting locale after initialization:**

<CodeGroup>
  ```bash bash theme={null}
  NoCodes.shared.setLocale("fr-FR")
  NoCodes.shared.showScreen(withContextKey: "yourContextKey")

  // Reset to system default
  NoCodes.shared.setLocale(nil)
  ```

  ```bash bash theme={null}
  NoCodes.shared.setLocale("fr-FR")
  NoCodes.shared.showScreen("yourContextKey")

  // Reset to system default
  NoCodes.shared.setLocale(null)
  ```

  ```bash bash theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```

  ```bash bash theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```

  ```bash bash theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```

  ```bash bash theme={null}
  NoCodes.GetSharedInstance().SetLocale("fr-FR");
  NoCodes.GetSharedInstance().ShowScreen("yourContextKey");

  // Reset to system default
  NoCodes.GetSharedInstance().SetLocale(null);
  ```

  ```bash bash theme={null}
  Qonversion.NoCodes.getSharedInstance().setLocale("fr-FR");
  Qonversion.NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  Qonversion.NoCodes.getSharedInstance().setLocale(null);
  ```

  ```bash bash theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```
</CodeGroup>

## Best Practices

Finalize your default-language copy before adding translations.

* Use variables for prices and durations to keep translations accurate as product metadata changes.
* Use AI Translation for an initial pass, then refine manually.
* Verify every language in the Preview Panel to ensure text fits your layout.
* Keep all languages close to 100% completion before publishing screens.

***

[Variables](variables-1)

[Fallbacks](fallbacks)


# Amazon S3
Source: https://documentation.qonversion.io/docs/amazon-s3

Send raw data reports directly to your Amazon S3 bucket

Qonversion allows you to upload all the raw revenue data we track to your Amazon S3 bucket. You can find more details about raw data reports [here](scheduled-reports).

## Prepare Amazon S3 credentials

To upload raw data reports to your bucket, Qonversion needs Access Key ID and Secret access key for the user with write access to the corresponding bucket.

1. Navigate to the [IAM Console](https://console.aws.amazon.com/iam/), select the *Users* section and click the *Add users* button

<img alt="2776" />

2. Select *Access key - Programmatic access* on the first step.

<img alt="2818" />

3. There is no need to add any permissions during the user creation; navigate to the final step.
4. Download the .csv file with the user's credentials; you will need them later.

<img alt="2758" />

5. Navigate to the recently created user and save the *User ARN* value; you will need it later.

<img alt="2756" />

6. [Navigate to your bucket list](https://console.aws.amazon.com/s3/), and create a new bucket or select an existing one.
7. Copy your bucket name.

<img alt="2860" />

8. Create a policy to allow the User ARN from the 5th step to get *PutObject* action access to the bucket from the 7th step.

   * For example, you can use [AWS Policy Generator](https://awspolicygen.s3.amazonaws.com/policygen.html), where *Principal = User ARN* and *Amazon Resource Name (ARN) = arn:aws:s3:::\[your bucket name from the 7th step]/\**
   * Or copy the JSON below after replacing *qonversion-test-bucket* and *arn:aws:iam::078705355735:user/QonversionFileUploader* in the *Resource* and *AWS* field, respectively, with your values.

<CodeGroup>
  ```json theme={null}
  {
    "Id": "Policy1672076420793",
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "Stmt1672070877286",
        "Action": [
          "s3:PutObject"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:s3:::qonversion-test-bucket/*",
        "Principal": {
          "AWS": [
            "arn:aws:iam::078705355735:user/QonversionFileUploader"
          ]
        }
      }
    ]
  }
  ```
</CodeGroup>

9. Final step to prepare Amazon S3 credentials. Navigate to the *Permissions* section in your bucket, click the *Edit* button in the *Bucket policy* field and paste the JSON from the previous step. Congratulations, after saving the changes, your configuration is ready to use!

<img alt="2752" />

## Enter Amazon S3 credentials to Qonversion

1. Navigate to the [Amazon S3](https://dash.qonversion.io/app/integration/create?name=amazon_s3) integration creation page.

<img alt="2176" />

2. Enter *AWS Access Key ID*, *AWS Secret Access Key* and *Bucket name* to the corresponding fields

   * You have gotten the *AWS Access Key ID* and *AWS Secret Access Key* values with the .csv file, downloaded during the 4th step in the *Prepare Amazon S3 credentials* section above.
   * You have gotten the bucket's name during the 7th step in the *Prepare Amazon S3 credentials* section above.

3. Click *the Add new integration +* button

4. Congratulations! Now you have successfully connected the Amazon S3 bucket to Qonversion. Navigate to the [Scheduled reports section](scheduled-reports#amazon-s3) to launch report uploading to the bucket.

***

What’s Next

* [Scheduled Reports](scheduled-reports)


# Amplitude
Source: https://documentation.qonversion.io/docs/amplitude

Send in-app subscription and purchases events to Amplitude

Qonversion sends all revenue events, including purchases in your app, subscriptions after free trials, renewals, and even refunds, to your Amplitude account. This allows you to match your user behavior with their payment history in Amplitude and inform your product decisions.

## 1. Setup the SDKs

1. Make sure you have Amplitude SDK installed. More about the Amplitude SDKs read [here](https://help.amplitude.com/hc/en-us/articles/205406607-SDKs).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Attribute events sent from Qonversion and events received from the Amplitude SDK to the same user by setting the same user ID to Amplitude that you set to Qonversion SDK using the [setProperty](user-properties) method.

<CodeGroup>
  ```swift Swift theme={null}
  Amplitude.instance()?.setUserId("yourSideUserID")
  ```

  ```objectivec Objective-C theme={null}
  [[Amplitude] instance] setUserId:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  Amplitude.getInstance().setUserId("yourSideUserID");
  ```

  ```kotlin Kotlin theme={null}
  Amplitude.getInstance().userId = "yourSideUserID"
  ```

  ```csharp Unity theme={null}
  Amplitude.Instance.init("AMPLITUDE_API_KEY", "yourSideUserID");
  ```
</CodeGroup>

<Warning>
  If your events from Qonversion do not attribute to users in Amplitude, please check that you are setting user IDs correctly with the SDK. User IDs must be strings with a length of 5 characters or more.
</Warning>

**→[Read more about user identifiers here](user-identifiers)**

## 2. Configure the Amplitude Integration

1. Navigate to your Amplitude's Manage Data Section, choose your app, and copy your API Key:

<img alt="" />

2. Navigate to the Integrations section in your Qonversion project, select [Amplitude](https://dash.qonversion.io/app/integration/amplitude), and provide the API Key.
3. If your Amplitude account is hosted on EU servers, switch your region settings to Europe in the Qonversion Amplitude integration settings.
4. You can use the default event names provided by Qonversion or change them as you need.

<Frame>
  <img />
</Frame>

**→[Read more about tracked events here](integrations-overview#tracked-events)**

<Check>
  ### Done!

  Now Qonversion will start sending in-app purchases and subscriptions data to your Amplitude account.
</Check>

## Event Payload

In case you need details about data sent to Amplitude, follow the example below:

Qonversion posts to Amplitude's `/2/httpapi` endpoint, which expects `{api_key, events: [...]}`. Each event includes the keys below. The advertising-id key is platform-dependent: iOS events include `idfa`, Android events include `adid`, and Stripe events omit both.

<CodeGroup>
  ```json theme={null}
  {
    "api_key": "<your Amplitude project API key>",
    "events": [
      {
        "user_id": "yourSideUserID",
        "time": 1590735145100,
        "productId": "native.subs.full.v3.month.14.99.trial.7d",
        "event_type": "trial_converted",
        "insert_id": "5942",
        "platform": "iOS",
        "revenueType": "trial_converted",
        "quantity": 1,
        "storefront": "USA",
        "app_version": "11.11",
        "os_name": "iOS",
        "os_version": "16.0",
        "device_model": "iPhone15",
        "country": "UK",
        "device_id": "A77BE955-4CFC-A4F5-69D081217E9D3B",
        "idfa": "00000000-0000-0000-0000-000000000000",
        "revenue": 2.39
      }
    ]
  }
  ```
</CodeGroup>

Amplitude only stores revenue in USD - non-USD currencies are converted server-side.

***

[Amazon S3](amazon-s3)

[AppMetrica](appmetrica)


# Analyse experiments
Source: https://documentation.qonversion.io/docs/analyse-experiment

Monitor your experiment results with real-time subscription analytics

The Analyse section in Qonversion Experiments provides the most critical experiment-related data:

* Control vs. Test Variant performance comparison
* Number of users exposed to each variant
* Number of days the experiment is running

Despite the ease of getting all the relevant experiment metrics in real-time, we highly recommend you remember *the Peeking problem* (checking the results and taking action before the A/B test is over). You should avoid accepting or rejecting your hypothesis before the results are statistically significant.

## Results Overview

The Overview tab is the first thing you see in the Experiments Analyse tab. Use it to monitor an experiment's progress quickly.

<img alt="" />

### Experiment result

The Experiment result section helps you understand if your results are statistically significant. Suppose the p-value exceeds 0.05 (statistical significance is not reached). In that case, we help you know the optimal sample size per variant to minimize the risk of false negatives and the impacts of temporal effects.

## Primary metric chart

Tracking your control vs. test variants' performance during the experiment is essential. Using this chart, you can see the results of your primary metric and select different metrics for the analyses.

Please note if you see the lines constantly intersecting, that might mean that the results are not statistically significant and you couldn't accept your hypothesis.

<img alt="" />

## Variants overview

Though each experiment aims to improve only one specific metric, paying attention to other related metrics is essential. Set metrics up in your Variants overview table, and keep an eye on the most important ones.

Please note that data and time filtering options from the [Primary metric chart](analyse-experiment#primary-metric-chart) apply to this table and the chart itself.

<img alt="" />

## Metrics you can analyze with Qonversion Experiments

### Users

Calculates as the number of users assigned to the specific variant.

### User-to-Trial Conversion

Calculates as the number of *Trial Started* events divided by the number of users assigned to the specific variant.

→ Numerator: *Trial Started* events from the cohort of users assigned to the variant for the selected period. → Denominator: Number of users assigned to the variant for the selected period.

### User-to-Paid Conversion

Calculates as the number of revenue (*Trial Converted, Subscription Started & In-App Purchase*) events divided by the number of users assigned to the specific variant.

→ Numerator: *Trial Converted, Subscription Started & In-App Purchase* events from the cohort of users assigned to the variant for the selected period. → Denominator: Number of users assigned to the variant for the selected period.

### New Trials

Calculates as the number of *Trial Started* events from the cohort of users assigned to the variant for the selected period.

### Trial-to-Paid Conversion

Calculates as the number of *Trial Converted* events divided by the number of *Trial Started* events from the cohort of users assigned to the specific variant.

→ Numerator: *Trial Converted* events attributed to *Trial Started* events. → Denominator: *Trial Started* events from the cohort of users assigned to the specific variant.

### Trials Cancellation Rate

Calculates as the number of *Trial Canceled* events divided by the number of *Trial Started* events from the cohort of users assigned to the specific variant.

→ Numerator: *Trial Canceled* events attributed to *Trial Started* events. → Denominator: *Trial Started* events from the cohort of users assigned to the specific variant.

### New Subscriptions

Calculates as the number of *Trial Converted* and *Subscription Started* events from the cohort of users assigned to the variant for the selected period. This includes both direct paid subscription starts and trial-to-paid conversions.

### Subscriptions Cancellation Rate

Calculates as the number of *Subscription Canceled* events divided by the number of *Subscription Started* events from the cohort of users assigned to the specific variant.

→ Numerator: *Subscription Canceled* events attributed to *SubscriptionStarted* events. → Denominator: *Subscription Started* events from the cohort of users assigned to the specific variant.

### Sales

Calculates as revenue (after deducting refunds) from the cohort of users assigned to the variant for the selected period.

### Proceeds

Calculates as [Sales](analyse-experiment#sales) after deducting App Stores' commission from the cohort of users assigned to the variant for the selected period.

### Refunds

Calculates as refund sum from the cohort of users assigned to the variant for the selected period.

***

What’s Next

* [Pause experiments](pause-experiments)
* [Stop experiments](finish-experiment)


# Analytics
Source: https://documentation.qonversion.io/docs/analytics

Access in-app subscription analytics in Qonversion dashboards with customizable filters, grouping, and currency conversion to track revenue and subscriber metrics.

<img alt="" />

## Overview

<Info>
  Note that all data is stored and represented in UTC time zone.
</Info>

To gain comprehensive insights into specific Dashboards, we recommend looking into the following guides for detailed information:

* [Monitoring](monitoring)
* [New User Overview](users#new-users-overview)
* [New-User-to-Trial Conversion](users#new-user-to-trial-conversion)
* [New-User-to-Paid Conversion](users#new-user-to-paid-conversion)
* [Active Trials](trials#active-trials)
* [New Trials](trials#new-trials)
* [Trials Movement](trials#trials-movement)
* [Trial-to-Paid Conversion](trials#trial-to-paid-conversion)
* [Trial Cancellation Rate](trials#trial-cancellation-rate)
* [Active Subscriptions](subscriptions#active-subscriptions)
* [New Subscriptions](subscriptions#new-subscriptions)
* [Subscriptions Movement](subscriptions#subscriptions-movement)
* [Subscriptions Cancellation Rate](subscriptions#subscriptions-cancellation-rate)
* [Sales](revenue#sales)
* [Proceeds](revenue#proceeds)
* [ARPU](revenue#arpu)
* [ARPPU](revenue#arppu)
* [Refunds](revenue#refunds)
* [Refund Rate](revenue#refund-rate)
* [MRR](revenue#mrr)
* [MRR Movement](revenue#mrr-movement)
* [ARR](revenue#arr)
* [ARR Movement](revenue#arr-movement)
* [Events](events-analytics)
* [Cohorts](cohorts)
* [Customers](customers)
* [Apple Search Ads](apple-search-ads-analytics)
* [Screen Analytics](no-codes-analytics)

***

## Filters and Groups

Filters enable you to narrow down charts to display data that aligns with specific attributes. This feature is handy when examining the performance of particular properties, such as a specific country, currency or app version.

On the other hand, groups allow you to dissect the overall totals in Analytics charts into distinct data segments. This functionality proves valuable when comparing the performance of specific properties.

### Available attributes

| Attribute          | Description                                                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Revenue event      | This filter organises data based on revenue events: **Trial Converted, Subscription Started, Subscription Renewed, Subscription Refunded, In-App Purchase** |
| Country            | This filter organises data based on the recorded device locale                                                                                              |
| Product            | This filter organises data based on the Product ID in the App Stores                                                                                        |
| Currency           | This filter organises data based on the currency in which the purchase was made                                                                             |
| Locale             | This filter organises data based on the Device language                                                                                                     |
| Device             | This filter organises data based on the Device type                                                                                                         |
| Device ID          | This filter organises data based on the Device ID (identifierForVendor or Settings Secure Android ID)                                                       |
| OS version         | This filter organises data based on the OS version                                                                                                          |
| App version        | This filter organises data based on the Application version                                                                                                 |
| SDK version        | This filter organises data based on the SDK version                                                                                                         |
| Custom User ID     | This filter organises data based on the Custom User ID, which is set with [setProperty](user-properties) method                                             |
| Qonversion User ID | This filter organises data based on the User ID generated by Qonversion                                                                                     |
| Media Source       | This filter organises data based on the Attribution Media Source (Apple Search Ads)                                                                         |
| Campaign           | This filter organises data based on the ASA Campaign                                                                                                        |
| Ad set             | This filter organises data based on the set of ASA advertising offers                                                                                       |
| Ad                 | This filter organises data based on the ASA advertising offer                                                                                               |

***

## Date Range

Choose the date range or custom amount of days up to the current day you want to analyse.

<img alt="" />

***

## Time Scale

Select the time scale for the x-axis of the charts. Opt for a day timescale to observe data at the finest level of detail. At the same time, lower resolutions like month allow you to identify broader trends over a longer period.

<img alt="" />

***

## Chart View

You can choose the chart view that best suits your data analysis needs, whether you prefer line charts, bar charts or any other type of chart.

<img alt="" />

<img alt="" />

<img alt="" />

***

## Export CSV

To export chart data, navigate to the desired chart in the Qonversion dashboard, locate the "Export CSV" button below the chart, and click on it.

<img alt="" />

## Currency Conversion

Qonversion uses currency conversion on the date of purchase. All rates come from [fixer.io](https://fixer.io) - Open-Source API for current and historical foreign exchange rates published by the European Central Bank.

## Display Currency

Charts that contain monetary data display values in USD by default. You can choose a different currency to view the data in. Values are converted using exchange rates matching the date of each data point.

Your currency preference is saved and persists across sessions.

***

[Apple Ads Integration](apple-search-ads)

[Monitoring](monitoring)


# Analytics Mode
Source: https://documentation.qonversion.io/docs/analytics-mode

Implement subscription analytics in 20 minutes without changing your existing in-app purchases flow.

Analytics (Observer) mode allows you to get the best-in-class analytics in minutes. You can also use [real-time subscriptions events](integrations-overview#tracked-events) in third-party integrations, webhooks, and get accurate Apple Search Ads attribution using this mode. You don't need to change your current in-app purchases flow.

After you install the SDK, follow the steps below.

## 1. Launch SDK

Initialize the SDK in Analytics mode:

<InitSdk />

**→[Get your Qonversion Project Key](quickstart#2-create-a-project-and-register-your-app)**

## 2. Sync Purchases

### iOS, StoreKit 2

#### Subscriptions only

In case you're using StoreKit Version 1, we automatically handle all the needed data about transactions that occurred. However, in the case of StoreKit Version 2, it is necessary to leverage the`syncStoreKit2Purchases()` SDK method. Call this function every time you receive a successful purchase result or auto-renewed transaction.

<CodeGroup>
  ```swift Swift theme={null}
  // In case you're using CocoaPods:
  QonversionSwift.shared.syncStoreKit2Purchases()

  // In case you're using Swift Package Manager:
  import QonversionSwift

  QonversionSwift.shared.syncStoreKit2Purchases()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] syncStoreKit2Purchases];
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().syncStoreKit2Purchases();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().syncStoreKit2Purchases();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SyncStoreKit2Purchases();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().syncStoreKit2Purchases();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().syncStoreKit2Purchases();
  ```
</CodeGroup>

#### Subscriptions & Consumables

In case you're using StoreKit Version 2 and selling Subscriptions and Consumables we recommend using **one** of these methods **before finishing transactions**:

<CodeGroup>
  ```swift Swift theme={null}
  await QonversionSwift.shared.syncStoreKit2Transactions()

  await QonversionSwift.shared.handleTransaction(transaction)

  await QonversionSwift.shared.handleTransactions(transactions)
  ```
</CodeGroup>

### Android

1. Check whether you have set your products up correctly. Make your GooglePlay subscriptions backwards compatible to have the best possible accuracy in Qonversion. [Learn more here](android-in-app-products)

2. While you are using Qonversion SDKs in Analytics Mode, in-app purchases implementation is entirely on your side. Remember to consume and acknowledge purchases to attribute them to users. **Otherwise, the purchases will be automatically refunded in 3 days.** See the official Android Developer documentation for [processing purchase details](https://developer.android.com/google/play/billing/integrate#process).

3. Sync data with Qonversion in your current purchase flow. Call `syncPurchases()` after every purchase.

<CodeGroup>
  ```java Java theme={null}
  Qonversion.getSharedInstance().syncPurchases();
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.syncPurchases()
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().syncPurchases();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().syncPurchases();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SyncPurchases();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().syncPurchases();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().syncPurchases();
  ```
</CodeGroup>

## 3. (Optional) Enable Server-to-Server notifications

Qonversion checks user receipts regularly and does not require server-to-server notifications from Apple or Google. Nevertheless, due to these notifications, your analytics charts, third-party integrations and webhooks will work much closer to real-time.

* Guide on [Apple Server-to-Server Notifications](ios-s2s-notifications)
* Guide on [Google Developer Notifications](google-developer-notifications)

## 4. Set additional user attributes

Optionally, to improve attribution in Adjust, AppsFlyer, Singular, or to match Qonversion revenue events to users in [third-party tools](integrations-overview), you can share with us such attributes as User Identifier, IDFA (Identifier for Advertisers, iOS 14.5+ only) or ASID (App set ID, Android 12+ only). Please, follow [this guide](user-properties#custom-user-properties) to learn more.

***

## Next steps

With Analytics Mode running, put your subscription data to work. For near real-time charts, also enable [Apple Server-to-Server Notifications](ios-s2s-notifications) and [Google Developer Notifications](google-developer-notifications).

<NextStepsAnalytics />


# Refund Keeper Analytics Overview
Source: https://documentation.qonversion.io/docs/analytics-overview

Refund Keeper doesn't just automate refund defense - it gives you full visibility into your refund activity and savings, all in one place.

Here's what you'll find inside the **Refund Keeper** Analytics section. For general subscription analytics, see [Subscriptions](/docs/subscriptions) and [Events](/docs/events-analytics).

## Analytic Widgets

<img alt="" />

### Requested Refunds

* Total number of refund requests submitted by users
* Total dollar value (\$) of requested refunds

### Won Back Refunds

* Number of refund requests successfully declined (blocked)
* Total dollar value (\$) of revenue saved from declined refunds

### Won Back Refunds Rate

* The percentage of refund requests Refund Keeper helped block.
* Calculated as `(Won Back Refunds / Requested Refunds) × 100`.

***

## Refund Activity Timeline Chart

* A dynamic timeline of refund requests and refunds won back over a selected period

<img alt="" />

## Detailed Refund Table

A table listing every refund request, with the following columns:

* **UID** - Qonversion user ID
* **Transaction id** - the platform transaction identifier
* **Product** - the product purchased
* **Status** - one of `Pending`, `Refunded` (refund approved by the store), or `Saved` (Refund Keeper successfully blocked the refund)
* **Price** - the refund amount, displayed in your selected currency
* **Date Created** - when the refund request was submitted

You can filter the table by tab (All / Pending / Refunded / Saved) and search by UID or transaction ID.

<img alt="" />

### Important Notes

***

1. **Refund Keeper** Analytics only tracks refund events where Refund Keeper was active.
2. Currently available for App Store refunds (Google Play refunds are not supported).
3. Requires Qonversion **Growth** or **Enterprise** Plan and **Server Notifications V2** enabled.

**Refund Keeper** makes it easy to see not just that you're saving revenue—but exactly how, where, and when you're doing it 🚀

***

[Enable Refund Keeper](enable-refund-keeper)

[Raw Data Export](raw-data-reports)


# Android 4.+ migration guide
Source: https://documentation.qonversion.io/docs/android-4-migration-guide

Historical migration guide for upgrading the Qonversion Android SDK to major version 4.+: instance-based initialization, renamed entities, and updated purchase and entitlement methods.

## Upgrading version

Increase the dependency version in your app *build.gradle* file to upgrade your Qonversion SDK to the latest version

<CodeGroup>
  ```groovy build.gradle theme={null}
  dependencies {    
       implementation 'io.qonversion.android.sdk:sdk:4.+'
  }
  ```
</CodeGroup>

## Initialization

Qonversion Android SDK 4 contains significant changes in how the library is initialized. We are moving from a singletons approach to the instance-based one. Before, you initialized Qonversion using the `launch` call:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  class App : Application() {
      override fun onCreate() {
          super.onCreate()
          Qonversion.launch(this, "projectKey", false)
      }
  }
  ```

  ```java Java theme={null}
  public class App extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          Qonversion.launch(this, "projectKey", false);
      }
  }
  ```
</CodeGroup>

Now, instead, you should create a `QonversionConfig` object using nested `Builder` and provide it to initialization method as follows:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  class App : Application() {
      override fun onCreate() {
          super.onCreate()
          val qonversionConfig = QonversionConfig.Builder(
              this,
              "projectKey",
              QLaunchMode.SubscriptionManagement
          ).build()
          Qonversion.initialize(qonversionConfig)
      }
  }
  ```

  ```java Java theme={null}
  public class App extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
                  this,
                  "projectKey",
                  QLaunchMode.Infrastructure
          ).build();
          Qonversion.initialize(qonversionConfig);
      }
  }
  ```
</CodeGroup>

Note that instead of providing the `observeMode` flag to the `launch` call, you should provide a concrete value from the `QLaunchMode` enum, depending on which mode you use Qonversion. Also, we've renamed our modes to make them more transparent for users:

* "Observe" mode becomes "Analytics" mode,
* "Infrastructure" mode becomes "Subscription Management" mode.

After the initialization, you can access the Qonversion instance whenever you want as follows:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  Qonversion.shared
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance();
  ```
</CodeGroup>

So you should replace all your Qonversion calls with the construction above.

Also, if you were using `Qonversion.setDebugMode()` for testing purposes, you should now call the `setEnvironment(QEnvironment.Sandbox)` method of the `QonversionConfig.Builder`.

As no `launch` method is available anymore, you won't get `QLaunchResult` as a result. The good news is that there are analogues for all the fields you might have been using from there:

* for `uid`, call `userInfo()` and get the `QUser.qonversionId` from the result,
* for `products` call `products()`,
* for `offerings` call `offerings()`,
* for `permissions` call `checkEntitlements()`,
* `experiments` field has no analogue, as the `experiments` method was removed for now.

## Entitlements

We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

| Version `<4`                  | Version 4+                     |
| ----------------------------- | ------------------------------ |
| QPermission                   | QEntitlement                   |
| QonversionPermissionsCallback | QonversionEntitlementsCallback |
| QProductRenewState            | QEntitlementRenewState         |
| QPermissionSource             | QEntitlementSource             |
| QPermissionsCacheLifetime     | QEntitlementsCacheLifetime     |
| checkPermissions              | checkEntitlements              |
| UpdatedPurchasesListener      | QEntitlementsUpdateListener    |

The `QEntitlement` class contains the same information as the `QPermission` with small renamings.

* `permissionsID` was renamed to `id`,
* `productID` was renamed to `productId`,
* `isActive` became a Kotlin property, so it should now be accessed as a property.

There is no `setUpdatedPurchasesListener` method in Qonversion. You should provide `UpdatedEntitlementsListener` to `QonversionConfig.Builder` during the initialization using the `setUpdatedEntitlementsListener` method. The same change is made to the `setPermissionsCacheLifetime` method. Now you can set the required lifetime using `QonversionConfig.Builder.setEntitlementsCacheLifetime` while Qonversion initialization.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val qonversionConfig = QonversionConfig.Builder(
      this,
      "projectKey",
      QLaunchMode.SubscriptionManagement
  )
      .setEntitlementsUpdateListener(object : EntitlementsUpdateListener {
          override fun onEntitlementsUpdated(entitlements: Map<String, QEntitlement>) {
              // handle updated entitlements
          }
      })
      .setEntitlementsCacheLifetime(QEntitlementsCacheLifetime.Year)
      .build()
  Qonversion.initialize(qonversionConfig)
  ```

  ```java Java theme={null}
  final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
          this,
          "projectKey",
          QLaunchMode.Infrastructure
  )
          .setEntitlementsCacheLifetime(QEntitlementsCacheLifetime.Year)
          .setEntitlementsUpdateListener(entitlements -> {/* handle updated entitlements */})
          .build();
  Qonversion.initialize(qonversionConfig);
  ```
</CodeGroup>

## Automation changes

We've also changed the way the `Automations` is used. As in Qonversion, you should use `Automations` via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.

<Info>
  ### You should access the shared instance of `Automations` strictly after you initialize Qonversion, else an exception will be thrown.
</Info>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  public class App : Application {
      override fun onCreate() {
          super.onCreate()
          val qonversionConfig = QonversionConfig.Builder(
              this,
              "projectKey",
              QLaunchMode.SubscriptionManagement
          ).build()
          Qonversion.initialize(qonversionConfig)
          Automations.shared.setDelegate(...)
      }
  }
  ```

  ```java Java theme={null}
  public class App extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
                  this,
                  "projectKey",
                  QLaunchMode.Infrastructure
          ).build();
          Qonversion.initialize(qonversionConfig);
          Automations.getSharedInstance().setDelegate(...);
      }
  }
  ```
</CodeGroup>

Also, the methods for working with push notifications were moved from `Qonversion` to `Automations`, so if you were using the following methods:

* `setNotificationsToken`,
* `handleNotification`,
* `getNotificationCustomPayload`, make sure to make calls from the Automations instance instead of the Qonversion one.

## Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

* all the internal classes and extensions are now marked as `internal`, so they won't be accessible from your code and won't pollute your project namespace (note that they are still accessible in java because of interoperability issues, but you should prevent using them as well). All these classes and extensions were moved to the `internal` package to make the library file structure more readable;
* the deprecated methods `resetUser`, `setUserId`, and `handleNotification(RemoteMessage)` were removed. `resetUser` was deprecated for a long time, and it did nothing, so there is nothing to replace this call with, remove the method if you were still using it for some reason. `setUserId` should be replaced with the `setProperty` call with `QUserProperties.CustomUserId` parameter. Instead of using the `handleNotification` method, accepting `RemoteMessage`, call the method of the same name, accepting the data map (`RemoteMessage.data`). Also note that the `handleNotification(Map<String, String>)` method was moved to the `Automations` class, as described above;
* the `firebase-messaging` dependency causing resolution collisions was removed;
* the `experiments` method was removed - we are now working on a new design of A/B experiments;
* `QEntitlementsCacheLifetime` enum values are rewritten in CamelCase to match the rest code style;
* the `AttributionSource` enum was renamed to `QAttributionProvider` and moved to the `dto` package;
* the `UserProperties` enum was renamed to the `QUserProperty` enum and moved to the `dto` package;
* the `checkTrialIntroEligibilityForProductIds` method was shortened to `checkTrialIntroEligibility`;
* added the new method `userInfo`, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
* added new enum values - `QOfferingTag.Unknown` and `QTrialDuration.Unknown`, which are used when parsing fails. `QTrialDuration.Unknown` is now a default value for the `QProduct.trialDuration` field, which is no longer nullable.

***

[iOS 3.+ migration guide](ios-3-migration-guide)

[Flutter 5.+ migration guide](flutter-5-migration-guide)


# Android 6.+ migration guide
Source: https://documentation.qonversion.io/docs/android-6-migration-guide

Historical migration guide for upgrading the Qonversion Android SDK to major version 6.+: renamed public methods, entities, and packages, with a before/after reference table.

## Upgrading version

Increase the dependency version in your app *build.gradle* file to upgrade your Qonversion SDK to the latest version

<CodeGroup>
  ```groovy build.gradle theme={null}
  dependencies {    
       implementation 'io.qonversion.android.sdk:sdk:6.+'
  }
  ```
</CodeGroup>

## Renamings

In this major version, we have renamed several entities, public methods and changed some packages to make our namings and structure more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade                                              | After upgrade                                                            |
| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
| `QUserProperty`                                             | `QUserPropertyKey`                                                       |
| `setUserProperty`                                           | `setCustomUserProperty`                                                  |
| `setProperty`                                               | `setUserProperty`                                                        |
| `com.qonversion.android.sdk.dto.QUserProperty`              | `com.qonversion.android.sdk.dto.properties.QUserPropertyKey`             |
| `com.qonversion.android.sdk.dto.QEntitlement`               | `com.qonversion.android.sdk.dto.entitlements.QEntitlement`               |
| `com.qonversion.android.sdk.dto.QEntitlementRenewState`     | `com.qonversion.android.sdk.dto.entitlements.QEntitlementRenewState`     |
| `com.qonversion.android.sdk.dto.QEntitlementSource`         | `com.qonversion.android.sdk.dto.entitlements.QEntitlementSource`         |
| `com.qonversion.android.sdk.dto.QEntitlementsCacheLifetime` | `com.qonversion.android.sdk.dto.entitlements.QEntitlementsCacheLifetime` |

## User properties changes

As mentioned above, we have renamed the `QUserProperty` enum to `QUserPropertyKey`. It was made to release the name `QUserProperty` for a class, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```java Java theme={null}
  Qonversion.getSharedInstance().userProperties(new QonversionUserPropertiesCallback() {
      @Override
      public void onSuccess(@NonNull QUserProperties userProperties) {
          for (QUserProperty property : userProperties.getProperties()) {
              Log.d("User property", "Key: " + property.getKey() +
                      ", value: " + property.getValue());
          }
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.userProperties(object : QonversionUserPropertiesCallback {
    override fun onSuccess(userProperties: QUserProperties) {
      userProperties.properties.forEach { 
        Log.d("User property", "key: ${it.key}, value: ${it.value}")
      }
    }

    override fun onError(error: QonversionError) {
      // handle error here
    }
  })
  ```
</CodeGroup>

`QUserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                  | Description                                                                                              |
| -------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `getProperty`        | `key` - string             | Searches for a property with the given property `key` in all properties list                             |
| `getDefinedProperty` | `key` - `QUserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `QUserPropertyKey` enum with several values:

* added a new property key `AdvertisingID`, which is used on iOS but can be received on Android due to cross-platform user management;
* added a `Custom` key to represent all the custom properties.

***

[iOS 5.+ migration guide](ios-5-migration-guide)

[Flutter 7.+ migration guide](flutter-7-migration-guide)


# Android SDK 6.x to 7.x migration guide
Source: https://documentation.qonversion.io/docs/android-7-migration-guide

We've upgraded the Google Play Billing Library dependency to version 6 in this release, which has led to major changes in the product and subscription management parts of our SDK. These are described below.

## Upgrading version

Increase the dependency version in your app *build.gradle* file to upgrade your Qonversion SDK to the latest version

<CodeGroup>
  ```groovy build.gradle theme={null}
  dependencies {    
       implementation 'io.qonversion.android.sdk:sdk:7.+'
  }
  ```
</CodeGroup>

## Product updates

### Qonversion and Google Play product link changes

Google Play has recently upgraded the structure of their subscription products. We've written about it [in our blog](https://qonversion.io/blog/google-play-billing-library-5-0/). In short, they combined the same subscriptions with different durations into a single subscription with different base plans. In addition, they announced different kinds of offers to base plans, including free trials or introductory prices. In this release, we begin to support those changes.

Previously Qonversion **subscription** products required a Google Play subscription identifier. Now you can also set a specific **base plan** for the subscription. Different base plans of the same subscription can be linked to different Qonversion products. Let's have a look at an example.

Let's say you sell monthly and annual subscriptions in your app, both on Android and iOS. With the previous Qonversion SDK versions, you would specify two Qonversion products (`premium_monthly` and `premium_annual`), two App Store products (`premium_monthly_ios` and `premium_annual_ios`), and two Google Play products (`premium_monthly_android` and `premium_annual_android`). Then you would link those store products to Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_monthly_android`,

`premium_annual` - `premium_annual_ios` and `premium_annual_android`.

With the new Google Play Subscriptions structure, you can create only one subscription for Android - `premium_android` and two base plans for it (`monthly` and `annual`). With this done, you can now use a single subscription for both Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_android` with `monthly` base plan,

`premium_annual` - `premium_annual_ios` and `premium_android` with `annual` base plan.

### Store details for the `QProduct` class

Speaking of the SDK side - the first big part of the changes is the addition of the new `basePlanId` field to `QProduct` which can be set to the product via Qonversion Dashboard.

We have deprecated the `QProduct.skuDetails` field, because `SkuDetails` contain information only for backward compatible base plans and are now deprecated in the Google Play Billing Library. Instead, we have added the new `storeDetails` field of type `QProductStoreDetails`, which contains all the store information for the Google Play Product. You can find the specifications of that class [on this page](google-play-product-details).

If `basePlanId` is not specified for a product, it means one of the following:

* it is a one-time (in-app) product that can not have any base plans,
* it is a product that was not updated in the Qonversion dashboard after this version was released.

In the case of the in-app product, both `skuDetails` and `storeDetails` fields will contain information about that in-app. But in the second case, when there is a subscription product without a specified base plan, the `skuDetails` field will contain information about the **backward compatible** base plan, while the `storeDetails` field will only contain common subscription information without base-plan-specific data. It means that you should start using `storeDetails` field for base-plan-specific data (like price, duration, and so on) for subscription products only if you've specified their base plan IDs in Qonversion product settings.

### The other `QProduct` fields changes

Along with the above changes, we have changed the `type` field and removed the `duration` and `trialDuration` fields from the product class. The `type` and `duration` were previously being set via the dashboard, and the `trialDuration` was calculated from the store details and was represented as an enumeration with several common durations. Now, the product `type` is calculated from the store details. We've also added the `Intro` value to `QProductType` to separate `trial` and `intro` products. An `Unknown` value was also added for the cases where we are unable to determine the product type. The `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod`. Both properties are of type `QSubscriptionPeriod` and the values are also calculated from the store details.

The last thing to note is that we've also changed the `prettyPrice` field calculation. Earlier it was calculated from `skuDetails`, while now we first try to use `storeDetails` if possible and only then fall back to `skuDetails`.

### `QProduct` updates summary

Below is the shortened summary of the `QProduct` changes:

* new `basePlanId` field, specifying concrete subscription base plan, added,
* `skuDetails` field deprecated,
* new `storeDetails` field, containing information about Google Play product, added;
* the `type` field is now calculated based on store details, instead of the value set via the Qonversion dashboard. The `Intro` and `Unknown` values were added to `QProductType` to separate cases of trial and intro products and also the case when we are unable to determine the product type;
* the `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod` fields of type `QSubscriptionPeriod` with the values calculated from the store details;
* the `prettyPrice` field now prefers `storeDetails` to get the price from, and only then - `skuDetails`.

## Purchase flow updates

In this release, we have changed the `purchase` and `updatePurchase` methods signatures. Previously there were several methods for different sets of arguments. Now we've arranged all those properties into classes - `QPurchaseModel` and `QPurchaseUpdateModel`, that should be instantiated and provided to the single `purchase` or `updatePurchase` method.

You can create instances of those classes either manually or by using the utility functions `toPurchaseModel` and `toPurchaseUpdateModel` added to the `QProduct` class.

Below is an example of how the `purchase` flow has changed:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Old
  Qonversion.shared.purchase(this, product, callback = object: QonversionEntitlementsCallback {...})

  // New
  val purchaseModel = product.toPurchaseModel()
  Qonversion.shared.purchase(this, purchaseModel, callback = object: QonversionEntitlementsCallback {...})
  ```

  ```java Java theme={null}
  // Old
  Qonversion.getSharedInstance().purchase(this, product, new QonversionEntitlementsCallback() {...});

  // New
  final QPurchaseModel purchaseModel = product.toPurchaseModel();
  Qonversion.getSharedInstance().purchase(this, purchaseModel, new QonversionEntitlementsCallback() {...});
  ```
</CodeGroup>

And an `updatePurchase` flow example:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Old
  Qonversion.shared.updatePurchase(this, product, "oldProductId", callback = object: QonversionEntitlementsCallback {...})

  // New
  val purchaseUpdateModel = product.toPurchaseUpdateModel("oldProductId")
  Qonversion.shared.updatePurchase(this, purchaseUpdateModel, callback = object: QonversionEntitlementsCallback {...})
  ```

  ```java Java theme={null}
  // Old
  Qonversion.getSharedInstance().updatePurchase(this, newProduct, "oldProductId", new QonversionEntitlementsCallback() {...});

  // New
  final QPurchaseUpdateModel purchaseUpdateModel = newProduct.toPurchaseUpdateModel("oldProductId");
  Qonversion.getSharedInstance().updatePurchase(this, purchaseUpdateModel, new QonversionEntitlementsCallback() {...});
  ```
</CodeGroup>

If you were using only product identifiers, you can create purchase models manually as follows:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Old
  Qonversion.shared.purchase(this, "productId", callback = object: QonversionEntitlementsCallback {...})

  // New
  val purchaseModel = QPurchaseModel("productId")
  Qonversion.shared.purchase(this, purchaseModel, callback = object: QonversionEntitlementsCallback {...})
  ```

  ```java Java theme={null}
  // Old
  Qonversion.getSharedInstance().purchase(this, "productId", new QonversionEntitlementsCallback() {...});

  // New
  final QPurchaseModel purchaseModel = new QPurchaseModel("productId");
  Qonversion.getSharedInstance().purchase(this, purchaseModel, new QonversionEntitlementsCallback() {...});
  ```
</CodeGroup>

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Old
  Qonversion.shared.updatePurchase(this, "newProductId", "oldProductId", callback = object: QonversionEntitlementsCallback {...})

  // New
  val purchaseUpdateModel = QPurchaseUpdateModel("newProductId", "oldProductId")
  Qonversion.shared.updatePurchase(this, purchaseUpdateModel, callback = object: QonversionEntitlementsCallback {...})
  ```

  ```java Java theme={null}
  // Old
  Qonversion.getSharedInstance().updatePurchase(this, "newProductId", "oldProductId", new QonversionEntitlementsCallback() {...});

  // New
  final QPurchaseUpdateModel purchaseUpdateModel = new QPurchaseUpdateModel("newProductId", "oldProductId");
  Qonversion.getSharedInstance().updatePurchase(this, purchaseUpdateModel, new QonversionEntitlementsCallback() {...});
  ```
</CodeGroup>

If necessary, you can provide a specific offer identifier for subscription purchase.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Specifying offer via the `toPurchaseModel` method:
  val productOfferDetails = ... // Choose an offer from `storeDetails`
  val purchaseModel = product.toPurchaseModel(productOfferDetails)

  // Specifying offer ID via the `toPurchaseModel` method:
  val purchaseModel = product.toPurchaseModel("offer_id")

  // Specifying offer ID via the constructor:
  val purchaseModel = QPurchaseModel("productId", "offer_id")
  val purchaseUpdateModel = QPurchaseUpdateModel("newProductId", "oldProductId", "offer_id")

  // Specifying offer ID after the purchase model creation:
  purchaseModel.offerId = "offer_id"
  ```

  ```java Java theme={null}
  // Specifying offer via the `toPurchaseModel` method:
  final QProductOfferDetails productOfferDetails = ...; // Choose an offer from `storeDetails`
  final QPurchaseModel purchaseModel = product.toPurchaseModel(productOfferDetails);

  // Specifying offer ID via the `toPurchaseModel` method:
  final QPurchaseModel purchaseModel = product.toPurchaseModel("offer_id");

  // Specifying offer ID via the constructor:
  final QPurchaseModel purchaseModel = new QPurchaseModel("productId", "offer_id");
  final QPurchaseUpdateModel purchaseUpdateModel = new QPurchaseUpdateModel("newProductId", "oldProductId", "offer_id");

  // Specifying offer ID after the purchase model creation:
  purchaseModel.setOfferId("offer_id");
  ```
</CodeGroup>

If provided, we will try to find and purchase the offer with the specified ID for the requested Qonversion product. If there is no offer with the specified ID, an error will be returned. If no offer ID is provided for the subscription purchase of Qonversion product with a specified base plan ID, then we will choose the most profitable offer for the client from all the available offers. We calculate the cheapest price for the client by comparing all the trial or intro phases and the base plan. For old Qonversion products (where the base plan ID is not specified), as well as for in-app products, the offer ID is ignored.

You can also remove any intro/trial offer from the purchase (use only a bare base plan). For that purpose, you should call `removeOffer` method of purchase model:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  purchaseModel.removeOffer()
  ```

  ```java Java theme={null}
  purchaseModel.removeOffer();
  ```
</CodeGroup>

## The other changes

* Google Play Billing Library version was upgraded from 6.0.1 to the latest 6.1.0;
* The minimal supported SDK version was upgraded from 16 to 19, the Kotlin version was also upgraded from 1.6 to 1.8;
* The `checkTrialIntroEligibility` method was improved and now detects the eligibility based on store details;
* `QonversionErrorCode.SkuDetailsError` was removed;
* The `QProductDuration` and `QTrialDuration` classes were removed;
* The previously deprecated method `contextForScreenIntent` was removed from `AutomationsDelegate`.

***

[\[Jan 2024\] Migration guide. Google Play Billing Library 6.](qonversion-sdk-major-version-copy)

[Flutter SDK 7.x to 8.x migration guide](flutter-8-migration-guide)


# Android SDK 7.x to 8.x migration guide
Source: https://documentation.qonversion.io/docs/android-8-migration-guide

We've upgraded the Google Play Billing Library dependency to version 7 in this release, leading to several changes in our SDK. These are described below.

## Upgrading version

Increase the dependency version in your app *build.gradle* file to upgrade your Qonversion SDK to the latest version

<CodeGroup>
  ```groovy build.gradle theme={null}
  dependencies {    
       implementation 'io.qonversion.android.sdk:sdk:8.+'
  }
  ```
</CodeGroup>

## Deployment upgrades

With the new Google Play Billing Library 7 we've increased our `minSdkVersion` to 21 and `targetSdkVersion` to 34.

If you were using lower `minSdkVersion` you should upgrade it to 21 to use the latest version of our SDK and Google Play Billing Library. If you have already targeted the 21+ version, you should do nothing.

## Installment plans support

In the latest library version, Google introduces installment plans, when a customer commits to pay for several subsequent subscription periods. In our release, we've added a new field `installmentPlanDetails` to `QProductOfferDetails` with the details of the installment plan if they exist. It contains the following information:

| Field                               | Type | Description                                                               |
| ----------------------------------- | ---- | ------------------------------------------------------------------------- |
| `commitmentPaymentsCount`           | Int  | Committed payments count after a user signs up for this subscription plan |
| `subsequentCommitmentPaymentsCount` | Int  | Subsequent committed payments count after this subscription plan renews   |

We've also added an `isInstallment` flag to `QProductStoreDetails` to check if the current product has an installment plan or not.

Below is an example of those fields usage:

<CodeGroup>
  ```java Java theme={null}
  Qonversion.getSharedInstance().products(new QonversionProductsCallback() {
    @Override
    public void onSuccess(@NonNull Map<String, QProduct> products) {
      QProduct installmentProduct = products.get("installmentProductId");
      if (installmentProduct == null) {
        // Product not found
        return;
      }

      QProductStoreDetails storeDetails = installmentProduct.getStoreDetails();
      if (storeDetails != null && storeDetails.isInstallment()) {
        QProductOfferDetails basePlan = storeDetails.getBasePlanSubscriptionOfferDetails();
        if (basePlan == null) {
          // No base plans exist
          return;
        }
        QProductInstallmentPlanDetails installmentPlanDetails = basePlan.getInstallmentPlanDetails();
        // Use the installment plan information
      }
    }

    @Override
    public void onError(@NonNull QonversionError error) {
  		// Handle error here
    }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.products(object : QonversionProductsCallback {
    override fun onSuccess(products: Map<String, QProduct>) {
      val installmentProduct = products["installmentProductId"]
      val storeDetails = installmentProduct?.storeDetails
      if (storeDetails?.isInstallment == true) {
        val installmentPlanDetails = storeDetails.basePlanSubscriptionOfferDetails?.installmentPlanDetails
        // Use the installment plan information
      }
    }

    override fun onError(error: QonversionError) {
  		// Handle error here
    }
  })
  ```
</CodeGroup>

## Fallback files

We're happy to introduce the fallback files support in this release to make our system reliability even higher. Fallback files allow your app to work as expected in rare cases of network connection or Qonversion API issues for new users without a cache available. This allows purchases and entitlements to be processed for new users even if the Qonversion API faces issues. This also makes it possible to receive remote configs for cases when the network connection is unavailable.

Read more about the fallback files in [the documentation](system-reliability#fallback-files).

## Error codes changes

In this release, we have renamed several `QonversionErrorCode` values to make them more clear.

| Old name              | New name                   |
| --------------------- | -------------------------- |
| `UnknownError`        | `Unknown`                  |
| `CanceledPurchase`    | `PurchaseCanceled`         |
| `ProductUnavailable`  | `StoreProductNotAvailable` |
| `ParseResponseFailed` | `ResponseParsingFailed`    |

If you were using any of the mentioned codes, please, update the names with the right column values.

## The other changes

* Pending purchases support was added for prepaid subscriptions.
* `QIntroEligibilityStatus` `NonIntroProduct` was renamed to `NonIntroOrTrialProduct` to better reflect the meaning.

***

[\[Jul 2024\] Migration guide. Google Play Billing Library 7.](jan-2024-migration-guide-google-play-billing-library-6-copy)

[Flutter SDK 8.x to 9.x migration guide](flutter-9-migration-guide)


# Android In-App Products Setup
Source: https://documentation.qonversion.io/docs/android-in-app-products

Create and configure Android in-app products and subscriptions in Google Play Console, including base plans, offers, pricing, and activation.

<Info>
  Creating in-app products before [granting users access](android-store-setup#6-grant-the-service-account-access-in-google-play-console) or [enabling the required Google Cloud APIs](android-store-setup#2-enable-the-required-google-apis) for the service account may cause problems with the receipt validation using Google Play Developer API. Google Play Developer API can return the following error *"The current user has insufficient permissions to perform the requested operation."*

  When encountering this issue, open the In-app products or Subscription tab respectively on the Google Play Console and make any updates. For example, edit the product description and save it.
</Info>

In order to create an in-app purchase navigate to [Google Play Developer Console](https://play.google.com/apps/publish/) and select the 'All apps' tab. Then select your app from the list.

<img alt="" />

Select **Products**. You can select either In-app products or Subscriptions.

<img alt="" />

**1. In-app products**

Let's choose the In-app products tab. Click the **Create product** button. You have to provide Product ID, Name, and Description.

<img alt="" />

<Warning>
  ### Note

  You can’t change the product ID after the product has been created.
</Warning>

Set the price at the bottom of the page and apply changes.

<img alt="" />

<Warning>
  ### Note

  Qonversion doesn't yet support multi-quantity purchases, so leave that option unselected.
</Warning>

Finally, check the tax and compliance settings and then click **Save**.

<img alt="" />

Once you have created a product, it has an **Inactive** status. Click the **Activate** button.

<img alt="" />

<img alt="" />

**2. Subscriptions**

Let's choose the Subscriptions tab. Click the **Create subscription** button. Provide Product ID and Name.

<img alt="" />

Now the subscription is created but it is not configured yet. There are four steps to configure it. Two of them are optional.

<img alt="" />

The first step is optional. You can add up to four custom strings explaining what users get when they subscribe.

<img alt="" />

For the next two steps, you should create base plans and offers, if necessary. The base plan contains basic information about the subscription such as duration, price, renewal type, grace period, etc.

<Info>
  You can check our [blog post](https://qonversion.io/blog/google-play-billing-library-5-0/) for the details of the new subscription model of Google Play.
</Info>

To create a base plan click **Add a base plan** either from the task list or from the base plans and offers section.

<img alt="" />

Enter the base plan identifier and configure its renewal type with billing and grace periods. You may also add tags that are used to distinguish base plans from the API side. This is not required with one base plan per subscription.

<img alt="" />

The last step is to set the price. Navigate to "Prices and availability" section and click **Set prices**, select regions the subscription will be available in and press **Set price**.

<img alt="" />

Enter the price and click **Update**. Save changes.

<img alt="" />

Once you have created a base plan, it has a **draft** status. Click the **Activate** button to make it available to users.

<img alt="" />

Your base plan is ready to use.

<img alt="" />

You can use the created subscription. You can also add options like a trial period or discounts to your subscriptions. This is where offers come in. Offers belong to base plans.

Click **Add offer** to create an offer.

<img alt="" />

Select the base plan to which the new offer will belong and click **Add offer**.

<img alt="" />

Specify offer identifier and select eligibility criteria. There are several options available: users who never bought this or any other subscriptions; those, who upgraded from other subscriptions; developer-determined.

You may also add tags as for the base plan.

<img alt="" />

The final step is phases. You can configure up to two phases which will be used before the base plan purchasing. For example, you can add a free trial for a week and a 10% discount for the next week before the user will buy the original subscription. To create a phase click the **Add phase** button in the Phases section.

<img alt="" />

Choose the phase type, duration, and, if you chose discount type, prices. In the example below we create a 10% discount price for a week.

<img alt="" />

Press **Apply** and **Save** to create an offer. The offer has a **draft** status. Press **Activate**.

<img alt="" />

After you have done all the above steps your subscription is ready to use.

***

[Google Play Store](google-play)

[Android test devices](android-test-devices)


# Android
Source: https://documentation.qonversion.io/docs/android-sdk

Install Qonversion Android SDK to implement in-app subscriptions, validate user receipts, get subscription analytics, and third-party integrations.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/android-sdk?label=Latest%20Release)](https://github.com/qonversion/android-sdk/releases)

## Install the library

The recommended way to install the Qonversion library for Android is with a build system like Gradle. The library is distributed via [Maven Central](https://search.maven.org).

Add the Qonversion library to the dependencies section in your app **build.gradle**

<CodeGroup>
  ```groovy build.gradle theme={null}
  dependencies {    
       implementation 'io.qonversion.android.sdk:sdk:9.+'
  }
  ```
</CodeGroup>

Or check the current release version on [Github](https://github.com/qonversion/android-sdk/releases) if you want to use a specific version.

## Kids Mode for Qonversion Android SDK

In case you are building an App for Kids, [follow this guide](kids-mode-sdk) to learn about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# Set up Google Play for Qonversion
Source: https://documentation.qonversion.io/docs/android-store-setup

How to create a Google Play service account, grant Qonversion access to the Google Play Developer API, and connect Real-Time Developer Notifications — the prerequisites for processing Android purchases through Qonversion.

Qonversion needs two things from your Google Play account: a **service account** with permission to read your app's billing data, and a Pub/Sub topic for **Real-Time Developer Notifications (RTDN)**. The wizard surfaces both as a single step; this guide walks through generating each piece on the Google side before pasting them in.

The flow spans two consoles — **Google Cloud Console** (sections 1–5) and **Google Play Console** (section 6) — and ends back in **Qonversion Dash** (section 7). Keep both Google tabs open; you'll switch between them.

## 1. Open the Google Cloud Console

1. Sign in to the [Google Cloud Console](https://console.cloud.google.com/welcome).
2. Pick the Google Cloud project that owns your app from the project picker at the top (or create one).
3. From **Quick access** on the welcome page, open **APIs & Services** — this is where you enable the integrations Qonversion needs.

<Frame>
  <img />
</Frame>

<Note>
  Use a project that's dedicated to this app (or shared across your apps). The service account you create later inherits this project's identity, so keep things tidy.
</Note>

## 2. Enable the required Google APIs

Three Google APIs need to be enabled on the same Cloud project:

* **Google Play Android Developer API** — lets Qonversion validate purchases and read subscription state.
* **Google Play Developer Reporting API** — surfaces RTDN delivery health in the Qonversion settings card.
* **Cloud Pub/Sub API** — required to provision the Real-Time Developer Notifications topic.

### 2.1 Open the API Library

In **APIs & Services**, click **Library** in the left sidebar.

<Frame>
  <img />
</Frame>

### 2.2 Find each API

Search by name (e.g. `Google Play Android Developer API`) and open the matching result. Repeat for the other two APIs.

<Frame>
  <img />
</Frame>

### 2.3 Enable each API

On every Product details page, click **Enable**. You'll repeat this for all three APIs.

<Frame>
  <img />
</Frame>

## 3. Create a service account

The service account is the identity Qonversion uses to call Google APIs on your behalf.

### 3.1 Open IAM & Admin

Return to the Cloud Console home (or use the search bar) and open **IAM & Admin** from **Quick access**.

<Frame>
  <img />
</Frame>

### 3.2 Start the service account form

In the left sidebar, click **Service Accounts**, then **+ Create service account** at the top.

<Frame>
  <img />
</Frame>

### 3.3 Name the service account

Give it a clear name like `Qonversion`. The Service account ID auto-fills from the name. Click **Create and continue** to move on.

<Frame>
  <img />
</Frame>

### 3.4 Grant the required roles

In the **Permissions** step, add two roles, then click **Done**:

* **Pub/Sub Admin** — required to provision and manage the RTDN topic.
* **Monitoring Viewer** — lets Qonversion surface RTDN delivery health on the settings card.

<Frame>
  <img />
</Frame>

## 4. Generate a JSON key

The JSON key is the credential Qonversion stores to authenticate as your service account.

### 4.1 Open the Keys tab and add a key

Open the service account you just created, switch to the **Keys** tab, click **Add key**, then **Create new key**.

<Frame>
  <img />
</Frame>

### 4.2 Choose JSON and create

Pick **JSON** (the recommended format) and click **Create**. The browser downloads the key file — save it somewhere safe.

<Frame>
  <img />
</Frame>

<Warning>
  The key file is downloadable only at creation time. If you lose it, delete the existing key from the Keys tab and generate a new one — the previous one stops working as soon as you revoke it.
</Warning>

## 5. Copy the service account's email

You'll need this email in a moment to invite the service account into Google Play Console.

In the **Service Accounts** list, click the email address (or its copy icon) — it looks like `<name>@<project-id>.iam.gserviceaccount.com`.

<Frame>
  <img />
</Frame>

## 6. Grant the service account access in Google Play Console

The service account exists in Google Cloud, but Google Play Console manages permissions separately — you need to invite it there too.

### 6.1 Open Users and permissions

In [Google Play Console](https://play.google.com/console), open **Users and permissions** from the left sidebar and click **Invite new users**.

<Frame>
  <img />
</Frame>

### 6.2 Paste the email and add your app under App permissions

Paste the service account email you copied in section 5 into **Email address**, then open the **App permissions** tab and add the app you're configuring.

<Frame>
  <img />
</Frame>

### 6.3 Switch to Account permissions and grant access

Open the **Account permissions** tab, tick these three checkboxes, then click **Invite user**:

1. **View app information and download bulk reports (read-only)**
2. **View financial data, orders, and cancellation survey responses**
3. **Manage orders and subscriptions**

<Frame>
  <img />
</Frame>

<Note>
  It can take up to 24 hours for Google's API to recognize new service-account permissions. If Qonversion shows "Please provide valid JSON credentials" right after pasting the key, give it a few hours and retry.
</Note>

## 7. Paste everything into Qonversion

Now jump back to **Qonversion Dash → Project Settings → Stores → Google Play Console**.

1. Paste your **Android Package Name**. This is the same value as `applicationId` in your app-level `build.gradle` — and the identifier Google Play Console lists against each app on the **Home** screen of your developer account.

   <Frame>
     <img />
   </Frame>

2. Upload the `.json` key file you downloaded in section 4.

3. Click **Connect to Google** to provision the RTDN Pub/Sub topic. Qonversion shows the topic name in the same row — copy it and paste it in Google Play Console → **Monetization setup → Real-time developer notifications**. See [Google Developer Notifications](google-developer-notifications) for the Play Console step.

4. Click **Save**.

<Frame>
  <img />
</Frame>

## Troubleshooting

### "Please provide valid JSON credentials"

* Wait up to 24 hours after granting Play Console access — propagation is slow.
* Make sure the service account is invited in **both** Google Cloud (as a service account) **and** Google Play Console (as a user with the three required Account permissions plus the app under App permissions).
* Confirm the JSON file's `client_email` matches the service-account email you invited.

### "The current user has insufficient permissions"

If you created your in-app products before granting the service account access, Google Play sometimes caches the old permission set. Open any in-app product on the Google Play Console, edit it lightly (e.g. tweak the description) and save — that nudges the cache.

### RTDN tag stays "Awaiting first notification" after a few minutes

* Trigger a sandbox subscription event (renewal, refund) — Google only sends notifications for actual events.
* Make sure **Pub/Sub Admin** is set on the service account; without it, Google can't publish to the topic.
* Check that **Cloud Pub/Sub API** is enabled in the same Google Cloud project.

### Lost the .json key

The Service Accounts → Keys tab lets you delete the old key and generate a new one. Re-upload the new file in the wizard — Qonversion will overwrite the stored credentials.

***

## What's next?

After this step, your Android configuration is complete. Test end-to-end:

* Make a sandbox purchase from a test device and confirm it appears in Qonversion within seconds.
* Trigger a refund or cancellation in Play Console and confirm the event arrives.


# Android test devices
Source: https://documentation.qonversion.io/docs/android-test-devices

Set up Android test devices, emulators, and license test accounts to safely test Google Play in-app purchases and subscriptions.

**1. Test devices** You can use both physical devices and emulators to run your app and test in-app purchases. Make sure that the emulator has the Play Store installed. You can check that by selecting **Tools->AVD Manager** in Android Studio.

<img alt="303" />

Emulators must use an emulator image with Google Play Store.

<img alt="" />

**2. Test account** The test account from the [License testing](license-testing) step must be added to the test device **first**.

**3. Add a PIN if needed** When you make an in-app purchase for the first time, Google may ask you to verify your account.

<img alt="" />

The following message may appear: "Something went wrong", even if you enter the correct password.

<img alt="382" />

To get rid of this error on your device navigate to **Settings->Accounts->** choose your account from the list.

<img alt="" />

Select Google Account: Info, security & personalization.

<img alt="" />

You have to finish signing in to continue. Click **Sign in**.

<img alt="372" />

Google advises to add a lock screen. Click the **Next** button.

<img alt="378" />

You can choose any convenient screen lock. For instance, let's choose **Continue without fingerprint**.

<img alt="" />

Select and set **PIN** for security.

<img alt="" />

<img alt="369" />

You may need to click on **Sign in** again to update the data. Finally the authorization process is over and you can make in-app purchases.

<img alt="368" />

***

[Android In-App Products Setup](android-in-app-products)

[Creating an App in Google Play Console](app-creation-in-google-play-console)


# Creating an App in Google Play Console
Source: https://documentation.qonversion.io/docs/app-creation-in-google-play-console

Walk through creating and configuring a new app in the Google Play Console before connecting it to Qonversion.

## 1. Create an app

Navigate to the [Google Play Console](https://play.google.com/console) and select the **All apps** tab from the menu on the left, then click **Create app**.

<Frame>
  <img />
</Frame>

Fill in the details required and click on **Create app**.

<img alt="" />

## 2. Set up the app

You have to complete the steps below to set up your app.

<img alt="" />

**2.1 App access** If your application has any forms of authentication, you have to provide the access details.

<img alt="" />

**2.2 Content ratings** Complete the questionnaire to receive your content ratings for the app.

<img alt="" />

**2.3 Target audience and content** Manage [target audience and app content](https://support.google.com/googleplay/android-developer/answer/9867159) settings.

<img alt="" />

**2.4 News app** Answer the question about the use of ads in your application.

<img alt="" />

**2.5 App category** Select your app category and provide your contact details.

<img alt="" />

**2.6 Set up the store listing** Fill in the app's name and description.

<img alt="" />

Provide the app icon and screenshots that will be shown on Google Play.

<img alt="" />

<img alt="" />

**2.7 Merchant account** If you don't have a merchant account yet, [create a payments profile](https://support.google.com/googleplay/android-developer/answer/7161426?hl=en).

**2.8 Set the price for your app**

<img alt="" />

<Warning>
  If you choose to offer your app for free, you cannot change that in the future.
</Warning>

***

What’s Next

* [App publication in Google Play Console](app-publication-in-google-play-console)
* [License testing](license-testing)
* [Android test devices](android-test-devices)
* [Android In-App Products Setup](android-in-app-products)


# Publish your Android App
Source: https://documentation.qonversion.io/docs/app-publication-in-google-play-console

If you want to test in-app purchases, your app must be published (either production, alpha or beta channels, ).

**1. Create closed track** Navigate to [Google Play Developer Console](https://play.google.com/apps/publish/) and select the 'All apps' tab. Then choose your app from the list. Select the **Testing->Closed Testing** tab in the left menu bar. Select Alpha from the Active tracks list and click **Manage track** opposite it.

<img alt="1853" />

Click on the **Create new release** button.

<img alt="" />

**2. Upload the signed .apk file** Upload the [signed](https://developer.android.com/studio/publish/app-signing#sign-apk) App Bundle or APK file.

<img alt="1562" />

After uploading the file, save the release.

<img alt="1574" />

**3. Add countries/regions for test** You can target your Beta track release to users in [specific countries](https://support.google.com/googleplay/android-developer/answer/7550024?hl=en). Add available countries to test the track.

<img alt="1169" />

**4. Configure a list of testers (Optional)** If you want your release to be available to certain users on Google Play, but not visible to anyone else, please specify a [list of testers](https://play.google.com/console/about/closed-testing/). Click the **Create email list** button.

<img alt="1084" />

Add email address and click **Save changes**.

<img alt="949" />

After the application is published, testers will be able to join your test.

<img alt="722" />

**5. Roll out** The release is currently in Draft status. Click the **Edit** button.

<img alt="438" />

Click the **Review release** button to check the release.

<img alt="399" />

If the release is ready, click the **Start rollout to Alpha** button.

<img alt="371" />

<Warning>
  ### Before making a purchase make sure your release is approved and available to selected testers.
</Warning>

<img alt="352" />

<Info>
  ### Publishing time

  When you publish your application for the first time, it may take up to several days. Later releases usually take several hours.
</Info>

<Warning>
  ### Make sure that the uploaded App Bundle or APK file matches the one you are testing when it comes to version code, version name, applicationId and keystore signature.
</Warning>

***

What’s Next

* [License testing](license-testing)
* [Android In-App Purchases Setup](android-in-app-products)
* [Android test devices](android-test-devices)


# App-Specific Shared Secret
Source: https://documentation.qonversion.io/docs/app-specific-shared-secret

App-Specific Shared Secret is a key to receive receipts for auto-renewable in-app subscriptions. See how to generate the app's shared secret below.

You need to provide the app-specific shared secret to Qonversion, so we can verify your in-app purchases. Qonversion provides out-of-the-box in-app subscription infrastructure. Learn more about [Qonversion](https://qonversion.io) and [sign up](https://dash.qonversion.io/site/signup?utm_source=docs\&utm_medium=docs\&utm_campaign=sharedsecret) for free.

Follow the steps below to get the shared secret for your iOS app:

## 1. Navigate to the In-App Purchases section in App Store Connect

1. [Log in](https://appstoreconnect.apple.com/login) to your App Store Connect account.
2. Choose [Apps](https://appstoreconnect.apple.com/apps) and select the App.
3. Select the App Information section from the left side menu.
4. Scroll down to the "App-Specific Shared Secret" label and click the "Manage" button.

<Frame>
  <img />
</Frame>

## 2. Generate the shared secret

Generate and copy your shared secret.

<Frame>
  <img />
</Frame>

***

What’s Next

Learn more about App Store Connect Shared Secret in our blog.

* [App Store Connect Shared Secret](https://qonversion.io/blog/app-store-connect-shared-secret/)


# App Store Connect API Key
Source: https://documentation.qonversion.io/docs/app-store-connect-api-key

How to create an App Store Connect API key and connect it to Qonversion so we can sync your product catalog and read your subscription grace period configuration.

The **App Store Connect API key** lets Qonversion read your app's metadata directly from App Store Connect. We use it to:

* **Auto-sync your in-app purchase catalog** so you don't have to mirror every product change in Qonversion by hand.
* **Read your subscription grace period configuration** so revenue and proceeds are attributed correctly when subscribers fall into a grace period.
* **Auto-detect your Bundle ID and App Store ID** during the onboarding wizard.

<Note>
  This is a **different key** from the [In-App Purchase API Key](in-app-purchase-api-key), which Qonversion uses for runtime transaction validation, refund detection, and subscription status. They're generated under different tabs in App Store Connect and they are **not interchangeable**.
</Note>

## 1. Make sure you have the right role

To generate an App Store Connect API key, your App Store Connect user must have one of these roles:

* **Account Holder**
* **Admin**
* **App Manager** — with access to every app you want Qonversion to manage

Contact your team's Account Holder if you don't have one of these roles.

## 2. Open the App Store Connect API tab

1. [Log in](https://appstoreconnect.apple.com/login) to App Store Connect.
2. Click **Users and Access** in the top navigation.
3. Open the **Integrations** tab.
4. Make sure the **App Store Connect API** sub-tab is selected (not "In-App Purchase").

<Frame>
  <img />
</Frame>

## 3. Generate a new key

1. Click **Generate API Key** (or **+** if you already have keys).
2. Give it a clear name, e.g. **Qonversion**.
3. Set **Access** to **Admin** or **App Manager** (App Manager is enough; Admin works too).
4. Click **Generate**.

<Frame>
  <img />
</Frame>

## 4. Copy the Key ID and Issuer ID, and download the .p8 private key

Everything you need lives on the same screen — copy the two identifiers and download the key file before leaving:

* Copy the **Key ID** (10-character string in the row of your new key) — this is the **Key Identifier** in Qonversion.
* Above the table, copy the **Issuer ID** (UUID format, e.g. `57246542-96fe-1a63-e053-0824d011072a`) — this is the **Issuer Identifier** in Qonversion.
* In the same row, click **Download API Key** to get the **.p8** file.

<Warning>
  Apple lets you download the `.p8` file **only once**. If you lose it, you have to revoke the key and create a new one. Save it somewhere safe before continuing.
</Warning>

<Frame>
  <img />
</Frame>

## 5. Paste everything into Qonversion

1. Open Qonversion Dash → **Project Settings** → **Stores** → **Apple App Store**.
2. Click **Configure App Store** (or **Edit configuration** if you've already started).
3. On **Step 1 · Identify your app**:
   * Paste the **Key ID** in the **Key Identifier** field.
   * Upload the `.p8` file in the **Private Key** field.
   * Paste the **Issuer ID** in the **Issuer Identifier** field.
4. Click **Verify & Fetch Apps**.

If everything is correct, Qonversion will show your apps and let you pick the one to configure — Bundle ID and App Store ID will be filled in automatically on the next step.

<Frame>
  <img />
</Frame>

## Troubleshooting

### "Failed to verify credentials" — HTTP 401 / NOT\_AUTHORIZED

* Make sure you pasted the **Key ID**, not the key name.
* Make sure the **Issuer ID** is from the **App Store Connect API** tab, not the In-App Purchase tab.
* Make sure the `.p8` file matches the Key ID you pasted.

### "No apps are linked to this API key"

The credentials are valid, but the API key role doesn't have access to any apps. If you're using **App Manager**, ask your **Admin** to grant the user explicit access to the apps you want to configure. **Admin** keys see all apps automatically.

### Lost the .p8 file

Apple does not let you re-download the file. Open **Users and Access → Integrations → App Store Connect API**, **revoke** the old key, then generate a new one and re-upload the new `.p8`.

***

## What's next?

After this step, finish the rest of the wizard:

* **Step 2 · Core setup** — paste your [App-Specific Shared Secret](ios-app-store-info-fields#2-generate-the-app-specific-shared-secret).
* **Step 3 · Server API access** — generate an [In-App Purchase API Key](in-app-purchase-api-key) (separate from this one) and upload it.
* **Step 4 · Production readiness** — copy the [Server-to-Server Notification URL](ios-s2s-notifications) into App Store Connect.


# App Store Privacy
Source: https://documentation.qonversion.io/docs/app-store-privacy

Understand what data is being collected by Qonversion for App Store reporting purposes

You’ll need to provide information about your app’s privacy practices to submit new and update existing apps in App Store Connect, including the practices of third-party partners whose code you integrate into your app. This information is required starting December 8, 2020. You can learn more [here](https://developer.apple.com/app-store/app-privacy-details/).

We have prepared a short guide on data that Qonversion collects to help you provide the required information to the App Store Connect.

Below is the list of the data types that Apple requires to report. We have indicated if Qonversion collects any specific type of data. App Store also requires to submit the purpose of data collection. You should select Analytics and App Functionality for the data types collected by Qonversion.

| Data Type          | Details                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Contact Info       | Not collected by Qonversion. *You can choose to use Qonversion [User Properties](user-properties) to store user name, email, and other contact information.* |
| Health and Fitness | Not collected by Qonversion                                                                                                                                  |
| Financial Info     | Not collected by Qonversion                                                                                                                                  |
| Location           | Not collected by Qonversion                                                                                                                                  |
| Sensitive Info     | Not collected by Qonversion                                                                                                                                  |
| Contacts           | Not collected by Qonversion                                                                                                                                  |
| User Content       | Not collected by Qonversion                                                                                                                                  |
| Browsing History   | Not collected by Qonversion                                                                                                                                  |
| Search History     | Not collected by Qonversion                                                                                                                                  |
| Identifiers        | **Qonversion collects User ID and Device ID.**                                                                                                               |
| Purchases          | **Qonversion collects App Store purchases history**                                                                                                          |
| Usage Data         | Not collected by Qonversion                                                                                                                                  |
| Diagnostics        | Not collected by Qonversion                                                                                                                                  |
| Other Data         | **Qonversion collects data on device OS, make, model, and resolution.**                                                                                      |

***

[App Store Offer Codes](appstore-offer-codes)

[App Store Promoted Purchases](app-store-promoted-purchases)


# App Store Promoted Purchases
Source: https://documentation.qonversion.io/docs/app-store-promoted-purchases

Promoting Your In-App Purchases on the App Store Page and Search Results

Promoted in-app purchases appear on your app page and can be displayed in search results. App Store promoted purchases are enabled by default. If a user starts an in-app purchase from the App Store, the purchase flow begins when a user opens your app.

<Info>
  Kindly note that the scenario described below is related only to the iOS platform.
</Info>

## iOS

### Set delegate

If you need additional logic, set `QONPromoPurchasesDelegate`.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setPromoPurchasesDelegate(self)
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setPromoPurchasesDelegate:self];
  ```
</CodeGroup>

### Add the following function to handle promoted purchases

<CodeGroup>
  ```swift Swift theme={null}
  func shouldPurchasePromoProduct(withIdentifier productID: String, executionBlock: @escaping Qonversion.PromoPurchaseCompletionHandler) {
      // check AppStore productID value in case you want to enable promoted purchase only for specific products
      
      let completion: Qonversion.PurchaseCompletionHandler = {result, error, flag in
        // handle the purchased product or error
      }
      
      // call this block if you want to allow promoted purchase or just store block and call when needed
      // do nothing and do not call block if you don't want to allow purchase
      executionBlock(completion)
    }
  ```

  ```objectivec Objective-C theme={null}
  - (void)shouldPurchasePromoProductWithIdentifier:(NSString *)productID executionBlock:(QONPromoPurchaseCompletionHandler)executionBlock {
    // check AppStore productID value in case you want to enable promoted purchase only for specific products
    
    QONPurchaseCompletionHandler completion = ^(NSDictionary<NSString *, QONEntitlement*> *result, NSError  *_Nullable error, BOOL cancelled) {
      // handle purchased product or error
    };
    
    // call this block if you want to allow promo purchase or just store block and call when needed
    // do nothing and do not call block if you don't want to allow purchase
    executionBlock(completion);
  }
  ```
</CodeGroup>

## Flutter

### Listen to the promo purchase stream

`Qonversion.promoPurchasesStream` emits AppStore `productID` whenever a promoted purchase flow is triggered. Listen to the stream to handle promoted purchases.

<CodeGroup>
  ```dart Flutter theme={null}
  StreamSubscription<String> _promoPurchasesStream;
  _promoPurchasesStream = Qonversion.getSharedInstance().promoPurchasesStream.listen((productID) async {
  	// check AppStore productID value in case you want to enable promoted purchase only for specific products
  	// call `Qonversion.promoPurchase` if you want to allow promoted purchase or just store productID and call when needed
  	// don't call `Qonversion.promoPurchase` if you don't want to allow purchase
  });
  ```
</CodeGroup>

### Complete the purchase

Call `Qonversion.promoPurchase` when you want to initialize the purchase (for example, immediately after the onboarding screens) and pass the AppStore `productID` as the parameter. Alternatively, call this method immediately on the app start.

<CodeGroup>
  ```dart Flutter theme={null}
  try {
    final entitlements = await Qonversion.getSharedInstance().promoPurchase(productID);
    // handle entitlements here
  } catch (e) {
    // handle error here
    print(e);
  }
  ```
</CodeGroup>

## React Native and Cordova

### Listen to promo purchases events

Provide `PromoPurchasesDelegate` to get notified whenever a promoted purchase flow is triggered.

<CodeGroup>
  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setPromoPurchasesDelegate({
      onPromoPurchaseReceived: async (productId, promoPurchaseExecutor) => {
          // check AppStore productId value in case you want to enable promoted purchase only for specific products
          // call `promoPurchaseExecutor` if you want to allow promoted purchase or just store productId and executor and call it when needed
          // don't call `promoPurchaseExecutor` if you don't want to allow purchase
      },
  });
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setPromoPurchasesDelegate({
      onPromoPurchaseReceived: async (productId, promoPurchaseExecutor) => {
          // check AppStore productId value in case you want to enable promoted purchase only for specific products
          // call `promoPurchaseExecutor` if you want to allow promoted purchase or just store productId and executor and call it when needed
          // don't call `promoPurchaseExecutor` if you don't want to allow purchase
      },
  });
  ```
</CodeGroup>

### Complete the purchase

Call the `promoPurchaseExecutor` provided to the delegate right in the delegate method or later when you want to initialize the purchase (for example, immediately after the onboarding screens) and pass the AppStore `productId` as the parameter.

<CodeGroup>
  ```typescript React Native theme={null}
  try {
      const entitlements = await promoPurchaseExecutor(productId);
      // handle entitlements here
  } catch (e) {
      // handle error here
  }
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await promoPurchaseExecutor(productId);
      // handle entitlements here
  } catch (e) {
      // handle error here
  }
  ```
</CodeGroup>

## Unity

### Handle events

`Qonversion.PromoPurchasesReceived` sends the event when a user initiates a promotional in-app purchase from the App Store. Declare a delegate to handle promo purchases. Promo purchases will proceed automatically if you are not using the`PromoPurchasesReceived` event.

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().PromoPurchasesReceived += HandlePromoPurchases;

  private void HandlePromoPurchases(string appStoreProductId, StartPromoPurchase startPromoPurchase)
  {
      // check AppStore productID value in case you want to enable promoted purchase only for specific products
      // call `startPromoPurchase` if you want to allow promoted purchase or just store productID and call when needed
      // don't call `startPromoPurchase` if you don't want to allow purchase
  }
  ```
</CodeGroup>

### Complete the purchase

Call `startPromoPurchase` when you want to initialize the purchase (for example, immediately after the onboarding screens).

<CodeGroup>
  ```csharp Unity theme={null}
  startPromoPurchase((entitlements, error) =>
  {
      if (error == null)
      {
          if (entitlements.TryGetValue("premium", out Entitlement premium) && premium.IsActive)
          {
              // Handle the active entitlement here
          }
      }
      else
      {
          // Handle the error  
          Debug.Log("Error" + error.ToString());
      }
  });
  ```
</CodeGroup>

***

[App Store Privacy](app-store-privacy)

[App Store Small Business Program](app-store-small-business-program)


# App Store Small Business Program
Source: https://documentation.qonversion.io/docs/app-store-small-business-program

Set up your App Store Small Business Program details in Qonversion

## 1. Apple Small Business Program Overview

* Existing developers who made up to 1 million USD in proceeds in 2020 for all their apps, as well as developers new to the App Store, can qualify for the program and the reduced commission. Navigate to your App Store Connect account to apply.
* If a participating developer surpasses the 1 million USD threshold, the standard commission rate will apply for the remainder of the year.
* If a developer’s proceeds fall below the 1 million USD threshold in a future calendar year, they can re-qualify for the 15% commission the year after.
* Developers must identify any Associated Developer Accounts to determine proceeds eligibility.

You can find the details of the program [here](https://qonversion.io/blog/how-to-enroll-in-the-new-app-store-small-business-program/). Enrollment is currently opened for the program.

## 2. Set up Small Business Program details in Qonversion

Qonversion can accurately calculate your app's proceeds after excluding Apple's commission taking into account your participation in the Small Business Program. You can choose to send the proceeds to any integration you use.

### Navigate to your project settings dashboard in Qonversion

You have to set the dates for your participation in the Small Business Program for each project you have with Qonversion. So if you have a number of apps don't forget to provide the details for each of them.

<Frame>
  <img />
</Frame>

### Select the dates for your participation in the program

Set the end date to the end of the next year if you don't expect to quit the program earlier. If at some point in time you chose to quit the program or you exceed the \$1M threshold don't forget to update the end date in Qonversion. Apple's commission after the end date will be calculated at a standard Apple rate.

<Frame>
  <img />
</Frame>

Please note that if you chose the start date earlier than the current date, Qonversion will not resend the data to integrations to avoid any duplicates.

***

[App Store Promoted Purchases](app-store-promoted-purchases)

[Apple Family Sharing](apple-family-sharing)


# Apple App Store
Source: https://documentation.qonversion.io/docs/apple-app-store

Overview of Qonversion's Apple App Store guides: offer codes, App Store privacy, promoted purchases, the Small Business Program, Family Sharing, promotional offers, and migrating from SwiftyStoreKit.

This section covers the Apple App Store features and setup steps you can use with Qonversion on iOS. Each guide is self-contained; pick the one that matches what you need to configure.

<CardGroup>
  <Card title="App Store Offer Codes" icon="ticket" href="appstore-offer-codes">
    Let users on iOS 14+ redeem offer codes through a one-time redemption URL or in-app via the `presentCodeRedemptionSheet` API.
  </Card>

  <Card title="App Store Privacy" icon="user-shield" href="app-store-privacy">
    Reference of the data types Qonversion collects so you can complete your App Store Connect app privacy details (report as Analytics and App Functionality).
  </Card>

  <Card title="App Store Promoted Purchases" icon="store" href="app-store-promoted-purchases">
    Show your in-app purchases on your App Store page and in search results. Promoted purchases are enabled by default and are iOS-only.
  </Card>

  <Card title="App Store Small Business Program" icon="building" href="app-store-small-business-program">
    Qualify for Apple's reduced 15% commission on up to 1 million USD in annual proceeds, and set up your program details in Qonversion.
  </Card>

  <Card title="Apple Family Sharing" icon="users" href="apple-family-sharing">
    Let a user share a subscription with up to 5 family members. Supported out-of-the-box in Subscription Management Mode once products and entitlements are configured.
  </Card>

  <Card title="Apple Promotional Offers" icon="tag" href="apple-promotional-offers">
    Re-engage lapsed subscribers or retain current ones with limited-time discounts and free trials on auto-renewable subscriptions (macOS, iOS, tvOS).
  </Card>

  <Card title="Migrate from SwiftyStoreKit" icon="arrow-right-arrow-left" href="swiftystorekit-alternative">
    Move your iOS app from SwiftyStoreKit to Qonversion to add server-side receipt validation, real-time monitoring, and subscription analytics.
  </Card>
</CardGroup>


# Apple Family Sharing
Source: https://documentation.qonversion.io/docs/apple-family-sharing

Apple Family Sharing allows a user to share a subscription with up to 5 other family members. Family Sharing can help increase customer engagement and improve retention of your app.

To begin, you can visit App Store Connect to turn on Family Sharing for a specific product. You can navigate to your apps page and select 'Turn On' in the Family Sharing section. Note that once you turn on Family Sharing for a product, you cannot turn it off.

<Frame>
  <img />
</Frame>

Qonversion [Subscription Management mode](subscription-management-mode) supports Family Sharing out-of-the-box. You just need to set up [your products and entitlements](subscription-management-mode#1-configure-products--entitlements). Family Sharing will be available automatically.

## Family Sharing Implementation

1. After the initial purchase, every family member will receive the transaction in`func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction])` method with `restored` type

2. You will only see the transactions from the first user who made a purchase in the Qonversion dashboards.

***

[App Store Small Business Program](app-store-small-business-program)

[Migrate from SwiftyStoreKit](swiftystorekit-alternative)


# Apple Promotional Offers
Source: https://documentation.qonversion.io/docs/apple-promotional-offers

Learn how to work with Apple Promotional Offers using Qonversion SDKs

<Info>
  ### This section is about [Apple Promotional Offers](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/implementing_promotional_offers_in_your_app)

  Please do not confuse them with [Apple Introductory Offers](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/implementing_introductory_offers_in_your_app) and [App Store Promoted Purchases](app-store-promoted-purchases), which are used for new users and for promoting your products through the App Store, respectively.
</Info>

Promotional offers are useful for re-engaging former subscribers or keeping current ones on board. Consider offering a limited-time discount or a free trial period for auto-renewable subscriptions on macOS, iOS, and tvOS. This can encourage lapsed users to return and help retain your existing subscriber base.

To use promotional offers in your app, you will need to complete a few steps:

1. Create a promotional offer in App Store Connect.
2. Connect your In-App Purchase API key in Qonversion. If you haven't set it up yet, follow the [In-App Purchase API Key](in-app-purchase-api-key) guide — it covers when, how, and where.
3. Use the new features of our SDK to obtain the promo offer and make a purchase with it.

### Create a promotional offer

Add your Promotional Offer in App Store Connect. You can find the instructions in the [official documentation](https://developer.apple.com/help/app-store-connect/manage-subscriptions/set-up-promotional-offers-for-auto-renewable-subscriptions).

### Generate a Private Key

Promotional offers are signed with your **In-App Purchase API key** — the same key you upload on **Step 3 · Server API access** of the iOS configuration wizard. If you haven't set it up yet, follow the [In-App Purchase API Key](in-app-purchase-api-key) guide — it covers when, how, and where.

### Get a promotional offer and make a purchase

The promotional offers you create in App Store Connect can be accessed within our SDK by calling `Qonversion.Product -> skProduct -> discounts`.

You can determine whether the user is eligible for a promotional offer based on your product’s business logic. Once you decide to grant the promotional offer to a user, you need to call the following function:

<CodeGroup>
  ```swift Swift theme={null}
  // You can obtain the product and discount in any other way. This approach is used here as an example.
  let mainProduct: Qonversion.Product = products["main"]
  let discount: SKProductDiscount? = mainProduct.skProduct?.discounts.first(where: { $0.identifier == "main_promo_offer" })
  Qonversion.shared().getPromotionalOffer(for: mainProduct, discount: discount) { promoOffer, error in
      // show paywall with promo offer
  }
  ```

  ```objectivec Objective-C theme={null}
  // You can obtain the product and discount in any other way. This approach is used here as an example.
  QONProduct *product = products[@"main"];
  NSArray *discounts = [product.skProduct.discounts filteredArrayUsingPredicate:[NSPredicate predicateWithBlock:^BOOL(SKProductDiscount *object, NSDictionary *bindings) {
    return [object.identifier isEqualToString:@"main_promo_offer"];
  }]];
  [[Qonversion sharedInstance] getPromotionalOfferForProduct:product discount:discounts.firstObject completion:^(QONPromotionalOffer * _Nullable promotionalOffer, NSError * _Nullable error) {
    // show paywall with promo offer
  }];
  ```

  ```dart Flutter theme={null}
  try {
    // You can obtain the product and discount in any other way. This approach is used here as an example.
    var promo = subscriptionProduct.skProduct?.discounts?.firstWhereOrNull(
      (discount) => discount.identifier == 'my_promo_offer_id'
    );

    if (promo != null) {
      var promoOffer = await Qonversion.getSharedInstance().getPromotionalOffer(subscriptionProduct, promo);
      // handle promo offer here
    }
  } on Exception catch (e) {
    // handle error here
  }
  ```

  ```typescript React Native theme={null}
  try {
    // You can obtain the product and discount in any other way. This approach is used here as an example.
    const promo = subscriptionProduct.skProduct?.discounts?.find(discount =>
        discount.identifier === 'my_promo_offer_id'
    );
    
    if (promo) {
      const promoOffer = await Qonversion.getSharedInstance().getPromotionalOffer(subscriptionProduct, promo);
    }
    // handle promo offer here
  } catch (e) {
      // handle error here
  }
  ```

  ```csharp Unity theme={null}
  var promo = subscriptionProduct.SkProduct?.Discounts?.Find(
    discount => discount.Identifier == "my_promo_offer_id"
  );

  if (promo != null) {
    Qonversion.GetSharedInstance().GetPromotionalOffer(subscriptionProduct, promo, (promoOffer, error) => {
      // Handle result here
    });
  }
  ```

  ```typescript Cordova theme={null}
  try {
    // You can obtain the product and discount in any other way. This approach is used here as an example.
    const promo = subscriptionProduct.skProduct?.discounts?.find(discount =>
        discount.identifier === 'my_promo_offer_id'
    );
    
    if (promo) {
      const promoOffer = await Qonversion.getSharedInstance().getPromotionalOffer(subscriptionProduct, promo);
    }
    // handle promo offer here
  } catch (e) {
      // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    // You can obtain the product and discount in any other way. This approach is used here as an example.
    const promo = subscriptionProduct.skProduct?.discounts?.find(discount =>
        discount.identifier === 'my_promo_offer_id'
    );
    
    if (promo) {
      const promoOffer = await Qonversion.getSharedInstance().getPromotionalOffer(subscriptionProduct, promo);
    }
    // handle promo offer here
  } catch (e) {
      // handle error here
  }
  ```
</CodeGroup>

After that, we will check on our server whether the user is eligible for this promotional offer. If they are, we will generate a signature for the purchase and return a `Qonversion.PromotionalOffer` object, which you will need to pass to the purchase function.

#### Determine eligibility

What availability conditions do we check for promotional offers? Those described in the [official documentation](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/implementing_promotional_offers_in_your_app#3150971). In the future, these options may be expanded.

We consider a user eligible for an offer if they have any active or expired subscription from any subscription group.

#### Make a purchase

To make a purchase with a promotional offer, take the object you received from the previous function, pass it into the purchase options object, and pass it to the `purchaseProduct` function.

<CodeGroup>
  ```swift Swift theme={null}
  let purchaseOptions = Qonversion.PurchaseOptions(promoOffer: promoOffer)
  Qonversion.shared().purchase(product, options: purchaseOptions) { (result) in
      // handle purchase result here
  }
  ```

  ```objectivec Objective-C theme={null}
  QONPurchaseOptions *purchaseOptions = [[QONPurchaseOptions alloc] initWithPromoOffer:promotionalOffer];
  [[Qonversion sharedInstance] purchaseWithResult:product
                                          options:purchaseOptions
                                       completion:^(QONPurchaseResult * _Nonnull result) {
    // handle purchase result here
  }];
  ```

  ```dart Flutter theme={null}
  var purchaseOptions = QPurchaseOptionsBuilder()
  		.setPromotionalOffer(promoOffer)
  		.build();

  var entitlements = await Qonversion.getSharedInstance().purchaseProduct(
    	subscriptionProduct,
    	purchaseOptions: purchaseOptions
  );
  ```

  ```typescript React Native theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setPromotionalOffer(promoOffer))
    .build();
  const entitlements = await Qonversion.getSharedInstance().purchaseProduct(
    subscriptionProduct,
    purchaseOptions
  );
  ```

  ```csharp Unity theme={null}
  var purchaseOptions = new PurchaseOptionsBuilder()
    	.SetPromotionalOffer(promoOffer)
    	.Build();
  Qonversion.GetSharedInstance().PurchaseProduct(
    subscriptionProduct,
    purchaseOptions,
    (entitlements, error, isCancelled) =>
    {
      ...
    });
  ```

  ```typescript Cordova theme={null}
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setPromotionalOffer(promoOffer))
    .build();
  const entitlements = await Qonversion.getSharedInstance().purchaseProduct(
    subscriptionProduct,
    purchaseOptions
  );
  ```

  ```typescript Capacitor theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setPromotionalOffer(promoOffer))
    .build();
  const entitlements = await Qonversion.getSharedInstance().purchaseProduct(
    subscriptionProduct,
    purchaseOptions
  );
  ```
</CodeGroup>

***

[Migrate from SwiftyStoreKit](swiftystorekit-alternative)

[Google Play Store](google-play)


# Apple Ads Integration
Source: https://documentation.qonversion.io/docs/apple-search-ads

Integrate Apple Search Ads attribution with Qonversion to measure in-app subscription revenue at the ad campaign level.

Qonversion automatically collects the attribution data for Apple Ads through its SDK and AdServices Framework. The attribution data and raw data export are available in the Qonversion Apple Ads dashboard.

## 1. Generate Apple Ads credentials

1. Create a user with the API Account Manager role in your Apple Ads [account](<https://app.searchads.apple.com/cm/app/ >) (you need the admin rights to create a user): Account Settings → User Management → Invite Users → Select the user role

2. Log in to your Apple Ads account using the user's credentials with API access created above. You need to create an **OAuth client** in the API settings. To generate private and public keys, please follow [Apple's Documentation](https://developer.apple.com/documentation/apple_search_ads/implementing_oauth_for_the_apple_search_ads_api#3733114). Paste your public key including "BEGIN" and "END" headers to create client credentials. Download the private key, you will need it later: Account Settings → API → Client Credentials

<Warning>
  ### Create a user with the API Account Manager role

  If you authorize using the main account, the credentials screen might not always appear. To prevent this issue, create a user with an API access role and use that account to authorize and retrieve the public key.
</Warning>

<img alt="" />

3. Copy and save `clientId`, `teamId`, `keyId`.
4. Fill **Public Key** with the public part of the certificate that you made in step 2.

## 2. Configure Qonversion with ASA credentials

1. Navigate to the [Apple Ads settings](https://dash.qonversion.io/project/apple-search-ads) in your Qonversion project

2. Provide your **Client ID**, **Team ID**, **Key ID**, **Private key** and save the information.

   1. Take **Client ID**, **Team ID**, **Key ID** from the Apple Ads account API settings page.
   2. Take **Private Key** from the private part of the certification mentioned above.
      1. Do not trim "-----BEGIN EC PRIVATE KEY-----" and "-----END EC PRIVATE KEY-----" from the private key. Paste it in our Settings as is.

<img alt="" />

## 3. Configure SDK

### 3.1 Enable Data Collection

After you have completed the first three steps from the [Quick Start guide](quickstart) and have Qonversion SDK installed, enable data collection using the following SDK method:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().collectAppleSearchAdsAttribution()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] collectAppleSearchAdsAttribution];
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().collectAppleSearchAdsAttribution();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().collectAppleSearchAdsAttribution();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().CollectAppleSearchAdsAttribution();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().collectAppleSearchAdsAttribution();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().collectAppleSearchAdsAttribution();
  ```
</CodeGroup>

<Warning>
  ### Tips

  1. Run `collectAppleSearchAdsAttribution` method regardless of user App Tracking Transparency (ATT) response; it allows us to collect attribution in the most accurate way
  2. Make sure you are using Qonversion iOS SDK version 2.18.2 or above
</Warning>

### 3.2 Import AdServices framework

Starting with iOS 14.3, Apple Ads campaigns are measured through a new self-attributing integration based on the [AdServices framework](https://developer.apple.com/documentation/ad_services).

<img alt="" />

<Check>
  ### Done

  You've successfully set up the Apple Ads attribution with Qonversion. Wait for a day and check the attribution data in Apple Ads dashboard in your Qonversion account.

  Please contact support if you don't see the Apple Ads dashboard in your Qonversion account.
</Check>

***

[Apple Ads](apple-search-ads-analytics)

[Analytics](analytics)


# Apple Ads
Source: https://documentation.qonversion.io/docs/apple-search-ads-analytics

Attribution and analytics dashboard for Apple Ads tracking

## Apple Ads Analytics Overview

Qonversion collects Apple Ads advertising attribution data so you can accurately measure the effectiveness of your campaigns and see exactly how much revenue each Apple Ads campaign and keyword generates. Qonversion Apple Ads tool tracks all critical metrics required for effective user acquisition on Apple's platform.

Qonversion accurately tracks in-app events, including trial conversions, subscription renewals, and in-app purchases, to define top-performing campaigns and keywords. Qonversion also shows you the data on ad spend, CPA, total revenue, and ROAS. The attribution dashboard leverages Apple Ads API and Ad Services framework, SDK data, and server-side receipt validation. Qonversion ASA attribution works independently of the SKAdNetwork.

<Note>
  In the Qonversion dashboard navigation this section is still labelled **Apple Search Ads** (route `/apple-search-ads`). Apple's marketing has moved to "Apple Ads", but the dashboard label has not been renamed yet.
</Note>

<iframe title="Qonversion Apple Ads Analytics overview" />

You can select the metrics in the dashboard and rearrange the columns by clicking the button at the top right corner of the Apple Ads table.

<Warning>
  Make sure you have configured [Apple Ads integration](apple-search-ads) correctly.
</Warning>

<Frame>
  <img />
</Frame>

## Available Metrics

<Warning>
  Note that metrics from Search Ads source are available only for Apple Search Ads Advanced campaigns.
</Warning>

Qonversion ASA dashboard tracks the following metrics:

| Available Columns         | Description                                                                                                                                                                                | Source: Qonversion | Source: Search Ads |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------------ |
| Ad Group Name             | Apple Ads Advanced campaigns contain ad groups with defined bids and audience settings. Each campaign can be made up of one or more ad groups.                                             |                    | ✅                  |
| ARPU                      | Average Revenue Per User. ARPU shows how much revenue a user brings to the company on average over a certain period.                                                                       | ✅                  |                    |
| ARPPU                     | Average Revenue Per (Paying) User - the metric that considers only paying customers, as opposed to ARPU.                                                                                   | ✅                  |                    |
| Average CPA               | Total Apple Ads Advanced campaign spend divided by the number of installs (downloads) received within a period.                                                                            |                    | ✅                  |
| Average CPM               | The average amount an Apple Ads Advanced advertiser pays per one thousand ad impressions on the App Store.                                                                                 |                    | ✅                  |
| Average CPT               | The average amount an Apple Ads Advanced advertiser has paid for a tap on their ad.                                                                                                        |                    | ✅                  |
| Impressions               | The number of times your Apple Ads Advanced ad appeared on the App Store within a particular period.                                                                                       |                    | ✅                  |
| Installs                  | The total number of conversions from new downloads and redownloads resulting from an ad within the reporting period. Apple Ads installs are attributed within a 30-day attribution window. |                    | ✅                  |
| Keyword                   | Someone may use a relevant word or term when searching for an app like yours. In your Apple Ads Advanced ad groups, you can add keywords your customers would search for on the App Store. |                    | ✅                  |
| New Downloads             | App downloads from new users who have never before downloaded your app.                                                                                                                    |                    | ✅                  |
| Purchases                 | The number of purchases within a particular period.                                                                                                                                        | ✅                  |                    |
| Redownloads               | Downloads from users who previously downloaded and deleted your app then redownloaded it again or downloaded the same app on an additional device after tapping your ad on the App Store.  |                    | ✅                  |
| Regular Subscriptions     | The number of subscriptions started within a particular period. This field does not include subscriptions with promotional periods (Trial or Introductory).                                | ✅                  |                    |
| Revenue                   | The total revenue from users acquired during the period selected, including subscription renewals.                                                                                         | ✅                  |                    |
| Spend                     | In Apple Ads Advanced, the sum of the cost of each customer taps on your ad over a particular period.                                                                                      |                    | ✅                  |
| Taps                      | The number of times users tapped your Apple Ads Advanced ad within a particular period.                                                                                                    |                    | ✅                  |
| Trials                    | The number of trials within a particular period.                                                                                                                                           | ✅                  |                    |
| Trials converted          | The number of started trial subscriptions that converted to paid subscribers.                                                                                                              | ✅                  |                    |
| Trial to paid conversion  | The percentage of started trial subscriptions that converted to paid subscribers.                                                                                                          | ✅                  |                    |
| Users                     | The number of detected by Qonversion new users within a particular period.                                                                                                                 | ✅                  |                    |
| User to trial             | The number of trial start events divided by the number of new users within a particular period.                                                                                            | ✅                  |                    |
| User to subscription      | The percentage of new users that converted to a subscriber.                                                                                                                                | ✅                  |                    |
| Return on ad spend (ROAS) | The revenue ratio generated by an advertiser's investment in Apple Ads. Campaign (or app promotion) revenue divided by ad cost x 100.                                                      | ✅                  | ✅                  |

***

[Customer Details](customer-details)

[Apple Ads Integration](apple-search-ads)


# AppMetrica
Source: https://documentation.qonversion.io/docs/appmetrica

Send in-app subscription and purchases events to AppMetrica

Qonversion sends [subscription events](integrations-overview#tracked-events) to AppMetrica to help you match your users' behavior with their payment history and inform your product decisions.

## 1. Setup the SDKs

1. Make sure you have AppMetrica SDK installed. More about the AppMetrica SDKs read [here](https://yandex.com/support2/appmetrica-io/en/sdk/platforms).

2. Set Qonversion SDK by following [installing the SDK guide](install-sdk).

3. To attribute sent from Qonversion events to a particular AppMetrica user, set AppMetrica Device ID Hash (`AppMetrica.deviceIDHash`):

   <CodeGroup>
     ```swift Swift theme={null}
     let completionBlock: (String?, Error?) -> Void = { deviceId, error in
       if let error = error {
         // Handle error here
       } else if let deviceId = deviceId {
         Qonversion.shared().setUserProperty(.appmetricaDeviceId, value: deviceId)
       }
     }

     // Specify the dispatch queue on which you want to execute the completion block, main queue as an example
     let queue = DispatchQueue.main // Use the main queue as an example

     YMMYandexMetrica.requestAppMetricaDeviceID(withCompletionQueue: queue, completionBlock: completionBlock)
     ```

     ```objectivec Objective-C theme={null}
     YMMAppMetricaDeviceIDRetrievingBlock completionBlock = ^(NSString * _Nullable deviceId, NSError * _Nullable error) {
       if (error) {
         // Handle error here
       } else {
         [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyAppMetricaDeviceId value:deviceId];
       }
     };

     // Specify the dispatch queue on which you want to execute the completion block, main queue as an example
     dispatch_queue_t queue = dispatch_get_main_queue();

     [YMMYandexMetrica requestAppMetricaDeviceIDWithCompletionQueue:queue
                                                    completionBlock:completionBlock];
     ```

     ```java Java theme={null}
     StartupParamsCallback startupParamsCallback = new StartupParamsCallback() {
         @Override
         public void onReceive(@Nullable Result result) {
             if (result != null) {
                 // Note, that `deviceIdHash` is used, not `deviceId`
                 Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.AppMetricaDeviceId, result.deviceIdHash);
             }
         }

         @Override
         public void onRequestError(@NonNull Reason reason, @Nullable Result result) {
             // ...
         }
     };
     AppMetrica.requestStartupParams(
             this,
             startupParamsCallback,
             Arrays.asList(
                     // Note, that `APPMETRICA_DEVICE_ID_HASH` is used, not `APPMETRICA_DEVICE_ID`
                     StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH
             )
     );
     ```

     ```kotlin Kotlin theme={null}
     val startupParamsCallback = object : StartupParamsCallback {
         override fun onReceive(result: StartupParamsCallback.Result?) {
             // Note, that `deviceIdHash` is used, not `deviceId`
             result?.deviceIdHash?.let {
                 Qonversion.shared.setUserProperty(QUserPropertyKey.AppMetricaDeviceId, it)
             }
         }

         override fun onRequestError(
             reason: StartupParamsCallback.Reason,
             result: StartupParamsCallback.Result?
         ) {
             // Handle error here
         }
     }
     AppMetrica.requestStartupParams(
         this,
         startupParamsCallback,
         listOf(
             // Note, that `APPMETRICA_DEVICE_ID_HASH` is used, not `APPMETRICA_DEVICE_ID`
             StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH
         )
     )
     ```

     ```dart Flutter theme={null}
     String deviceId = await AppMetrica.requestAppMetricaDeviceID();
     Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.appMetricaDeviceId, deviceId);
     ```

     ```typescript React Native theme={null}
     AppMetrica.requestAppMetricaDeviceID((deviceId, reason) => {
       if (deviceId) {
         Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.APP_METRICA_DEVICE_ID, deviceId);
       } else {
         // Handle error here
       }
     });
     ```

     ```csharp Unity theme={null}
     AppMetrica.Instance.RequestAppMetricaDeviceID((deviceId, error) =>
         {
             if (error != null)
             {
                 // Handle error here
             }
             else
             {
                 Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.AppMetricaDeviceId, deviceId);
             }
         });
     ```
   </CodeGroup>

4. (Optionally) To improve attribution quality, set the same user ID to AppMetrica and Qonversion SDKs:

   <CodeGroup>
     ```swift Swift theme={null}
     YMMYandexMetrica.setUserProfileID("yourSideUserID")
     Qonversion.shared().setUserProperty(.appMetricaUserProfileId, value: "yourSideUserID")
     ```

     ```objectivec Objective-C theme={null}
     [YMMYandexMetrica setUserProfileID:@"yourSideUserID"];
     [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyAppMetricaUserProfileId, value: @"yourSideUserID";
     ```

     ```java Java theme={null}
     AppMetrica.setUserProfileID("yourSideUserID");
     Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.AppMetricaUserProfileId, "yourSideUserID");
     ```

     ```kotlin Kotlin theme={null}
     AppMetrica.setUserProfileID("yourSideUserID")
     Qonversion.shared.setUserProperty(QUserPropertyKey.AppMetricaUserProfileId, "yourSideUserID")
     ```

     ```dart Flutter theme={null}
     await AppMetrica.setUserProfileID('yourSideUserID');
     Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.appMetricaUserProfileId, 'yourSideUserID');
     ```

     ```typescript React Native theme={null}
     AppMetrica.setUserProfileID('yourSideUserID');
     Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.APP_METRICA_USER_PROFILE_ID, 'yourSideUserID');
     ```

     ```csharp Unity theme={null}
     AppMetrica.Instance.SetUserProfileID("yourSideUserID");
     Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.AppMetricaUserProfileId, "yourSideUserID");
     ```
   </CodeGroup>

## 2. Configure the AppMetrica integration

1. Navigate to your [AppMetrica dashboard](https://appmetrica.yandex.com/), select Settings and collect the following keys:

   1. **Application ID**. It can be found right below the Application name in the General tab.
   2. **Post API key**. It can be found in the General settings section as well.

<img alt="" />

2. Navigate to the [Integrations](https://dash.qonversion.io/app/integration/) section of your Qonversion project, select [AppMetrica](https://dash.qonversion.io/app/integration/create?name=appmetrica), provide the **Application ID** and **Post API key**, and click Save.

<img alt="" />

3. You can use the default event names provided by Qonversion or change them as you need.

**→[Read more about tracked events here](integrations-overview#tracked-events)**

<Check>
  ### Done

  Now Qonversion starts sending in-app purchases and subscription data to your AppMetrica account.
</Check>

## Event Payload

In case you need details about data sent to AppMetrica, follow the example below:

<CodeGroup>
  ```json JSON theme={null}
  {
    "post_api_key": "your_post_api_key",
    "application_id": "your_application_id",
    "revenue_event_type": "example_event_type",
    "event_timestamp": "1707206995",
    "product_id": "example_product_id",
    "app_package_name": "com.example.app",
    "appmetrica_device_id": "8f65b16df378e7a6bece9614e1530fb55",
    "price": "19.99",
    "currency": "USD",
    "transaction_id": "example_transaction_id",
    "order_id": "example_order_id",
    "ios_ifa": "example_advertising_id_for_ios",
    "google_aid": "example_advertising_id_for_android",
    "os_name": "iOS",
    "os_version": "15.0",
    "device_model": "iPhone13,2",
    "device_locale": "en_US",
    "app_version_name": "1.0.0"
  }
  ```
</CodeGroup>

***

[Amplitude](amplitude)

[AppsFlyer](appsflyer)


# AppsFlyer
Source: https://documentation.qonversion.io/docs/appsflyer

Send Qonversion in-app subscription events to AppsFlyer for accurate revenue tracking of trials, conversions, renewals, and refunds.

Accurately measure what drives your subscription revenue on an ad campaign level by tracking events like trial-to-paying-user conversions, renewals, refunds, and upgrades. Qonversion tracks revenue even if a user does not open your app. This allows you to measure the performance of each subscription plan with 100% accuracy.

## 1. In your app: set up the SDKs

1. You need to have the AppsFlyer SDK integrated into your app before starting with this integration. If you do not have AppsFlyer integration yet, please use [this documentation](https://support.appsflyer.com/hc/en-us/articles/207032066-iOS-SDK-integration-for-developers).

2. Set Qonversion SDKs following [Installing the SDKs](install-sdk) guides.

3. Send AppsFlyer user ID to Qonversion via [User Properties](user-properties). In the **onConversionDataSuccess** callback use the`setProperty()` method with the AppsFlyer user ID value.

<CodeGroup>
  ```swift Swift theme={null}
  // AppsFlyer 6

  import AppsFlyerLib
  extension AppDelegate: AppsFlyerLibDelegate {

      func onConversionDataSuccess(_ conversionInfo: [AnyHashable : Any]!) {
          Qonversion.shared().setUserProperty(.appsFlyerUserID, value: AppsFlyerLib.shared().getAppsFlyerUID())
      }
      
      func onConversionDataFail(_ error: Error!) {
      
      }
  }

  // Appsflyer 5

  import AppsFlyerLib
  extension AppDelegate: AppsFlyerTrackerDelegate {

      func onConversionDataSuccess(_ conversionInfo: [AnyHashable : Any]!) {
          Qonversion.shared().setUserProperty(.appsFlyerUserID, value: AppsFlyerTracker.shared()?.getAppsFlyerUID())
      }
      
      
      func onConversionDataFail(_ error: Error!) {
      
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  /// AppsFlyer 6
    
  #import <AppsFlyerLib/AppsFlyerLib.h>

  @interface AppDelegate: UIResponder <UIApplicationDelegate, AppsFlyerLibDelegate>

  - (void)onConversionDataSuccess:(NSDictionary *)conversionInfo {
      [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyAppsFlyerUserID value:[[AppsFlyerLib shared] getAppsFlyerUID]];
  }

  - (void)onConversionDataFail:(NSError *)error {

  }

  @end

  /// AppsFlyer 5

  #import <AppsFlyerTracker/AppsFlyerTracker.h>

  @interface AppDelegate: UIResponder <UIApplicationDelegate, AppsFlyerTrackerDelegate>

  - (void)onConversionDataSuccess:(NSDictionary *)conversionInfo {
      [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyAppsFlyerUserID value:[[AppsFlyerTracker sharedTracker] getAppsFlyerUID]];
  }

  - (void)onConversionDataFail:(NSError *)error {

  }

  @end
  ```

  ```java Java theme={null}
  AppsFlyerConversionListener conversionListener = new AppsFlyerConversionListener() {

      @Override
      public void onConversionDataSuccess(final Map<String, Object> conversionData) {
          Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.AppsFlyerUserId, AppsFlyerLib.getInstance().getAppsFlyerUID(App.this));
      }

      @Override
      public void onConversionDataFail(String errorMessage) {

      }

      @Override
      public void onAppOpenAttribution(Map<String, String> conversionData) {

      }

      @Override
      public void onAttributionFailure(String errorMessage) {

      }
  };

  AppsFlyerLib.getInstance().init("afDevKey", conversionListener, this);
  ```

  ```kotlin Kotlin theme={null}
  val conversionListener: AppsFlyerConversionListener = object : AppsFlyerConversionListener {
      override fun onConversionDataSuccess(conversionData: Map<String, Any>) {
          Qonversion.shared.setUserProperty(
              QUserPropertyKey.AppsFlyerUserId,
              AppsFlyerLib.getInstance().getAppsFlyerUID(this@App)
          )
      }

      override fun onConversionDataFail(errorMessage: String) {}
      override fun onAppOpenAttribution(conversionData: Map<String, String>) {}
      override fun onAttributionFailure(errorMessage: String) {}
  }

  AppsFlyerLib.getInstance().init("afDevKey", conversionListener, this)
  ```

  ```dart Flutter theme={null}
  _appsflyerSdk.onInstallConversionData((res) {
    print("res: " + res.toString());
    setState(() {
      _gcd = res;
    });

    Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.appsFlyerUserId, 'your appsflyer user id');
  });
  ```

  ```typescript React Native theme={null}
  this.onInstallConversionDataCanceller = appsFlyer.onInstallConversionData(
    (res) => {    
      appsFlyer.getAppsFlyerUID((err, appsFlyerUID) => {
        if (err) {
          console.error(err);
        } else {
          Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.APPS_FLYER_USER_ID, appsFlyerUID);
        }
      });
    }
  );
  ```

  ```csharp Unity theme={null}
  using AppsFlyerSDK;
  using QonversionUnity;

  public class AppsFlyerObjectScript : MonoBehaviour , IAppsFlyerConversionData
  {
      void Start()
      {
          /* AppsFlyer.setDebugLog(true); */
          AppsFlyer.initSDK("devkey", "appID", this);
          AppsFlyer.startSDK();
      }

      public void onConversionDataSuccess(string conversionData)
      {
          Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.AppsFlyerUserId, AppsFlyer.getAppsFlyerId());
      }
  }
  ```
</CodeGroup>

<Warning>
  ### Do not track any purchase events on the client side

  Qonversion tracks all revenue events so if you track revenue events with AppsFlyer SDK, you may double count the revenue in your AppsFlyer account.
</Warning>

## 2. In stores

1. Get your App ID. You can find the App ID in the App Store URL:

   1. **For iOS**
      ```
      https://apps.apple.com/us/app/apple-developer/640199958
      ```
   2. **For Android**
      ```
      https://play.google.com/store/apps/details?id=com.android.chrome
      ```

## 3. In AppsFlyer

1. Get the AppsFlyer Dev Key in your AppsFlyer account,
   1. Go to **Configuration → App Settings → Dev Key** and get it

2. Set up receiving events with S2S in the AppsFlyer

   1. If your selected mode is SKAN 4 or Custom:
      1. No settings changes are required.

   2. If your selected mode is revenue, conversion, or engagement:

      1. In AppsFlyer, go to Settings > SKAN Conversion Studio.
      2. Click options (⋮).
      3. Turn on Record in-app events sent by server-to-server API.
      4. Send events by S2S.

<Info>
  Read more: [https://support.appsflyer.com/hc/en-us/articles/4403727223185-SKAN-Conversion-Studio#report-events-by-servertoserver-api](https://support.appsflyer.com/hc/en-us/articles/4403727223185-SKAN-Conversion-Studio#report-events-by-servertoserver-api)
</Info>

## 4. Configure the AppsFlyer integration on Qonversion's side

### Provide Integration Details

1. Navigate to the Integrations section in your Qonversion project, select [AppsFlyer](https://dash.qonversion.io/app/integration/appsflyer), and provide the Dev Key and App ID, and Save

   1. Put in the Dev Key from the AppsFlyer
   2. Put in App ID

<Frame>
  <img />
</Frame>

### Configure the event names

We recommend using the default event names provided by Qonversion. However, you can change the event names to suit your preferences. Note that the event names will not affect revenue recognition. All purchase events containing a value (subscription started, trial converted, subscription renewed, subscription refunded, in-app purchase) will be sent to AppsFlyer with the af\_revenue property, and the revenue will be recognized correctly in AppsFlyer.

**→[Read more about tracked events here](integrations-overview#tracked-events)**

### Enable the integration

<Check>
  ### Done!

  Now Qonversion will start sending in-app purchases and subscriptions data to your AppsFlyer account.
</Check>

## Details

### About our event payload

In case you need details about data sent to AppsFlyer, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
    "appsflyer_id": "",
    "os": "14.6",
    "app_version_name": "1.0.0",
    "customer_user_id": "outside_uid",
    "idfa": "",
    "idfv": "",
    "eventCurrency": "EUR",
    "ip": "",
    "bundleIdentifier": "com.app.name",
    "eventName": "trial_converted",
    "storefront": "USA",
    "eventTime": "Y-m-d H:i:s.u",
    "eventValue": {
      "af_content_type": "product",
      "af_content_id": "product_id",
      "q_uid": "QON_...",
      "af_revenue": "1.99",
      "af_currency": "EUR"
    }
  }
  ```
</CodeGroup>

Notes:

* `appsflyer_id` is generated by AppsFlyer.
* `customer_user_id` is the unique user identifier set by the app owner.
* `bundleIdentifier` is the app bundle ID from App Store Connect.
* `eventTime` is UTC. AppsFlyer needs to receive each event by 02:00 UTC of the following day; otherwise AppsFlyer falls back to the time it received the event.

<Info>
  ### Check out the sample Xcode Project

  [Here](https://github.com/qonversion/qonversion-ios-sdk/tree/develop/Sample) you can find the sample Xcode project that demonstrates the Qonversion and AppsFlyer integration
</Info>

## How to compare your app revenue in AppsFlyer to Qonversion

Navigate to your **AppsFlyer → Activity** dashboard. The date range relates to the event date and isn't LTV-based. The revenue you see in this dashboard is the revenue generated for the selected period. Revenue consists of in-app purchases (if reported) and ad revenue.

To compare the total revenue from this dashboard to the revenue tracked by Qonversion:

1. Navigate to the Qonversion [Customers](http://dash.qonversion.io/customers/index) dashboard.
2. Select the same date range.
3. See the "Sales" figure at the top right.

This sales figure should be equal to your revenue in AppsFlyer. Please note:

1. The sales data in Qonversion is before deducting app stores commissions. If you are sending the revenue to AppsFlyer net of App Store commission (step 1 (4) of this guide above), the sales number will be 15-30% higher in Qonversion than in AppsFlyer.
2. Qonversion does not track ad revenue
3. Qonversion Customers dashboard data does not contain one-off in-app purchases.

There also might be a minor difference due to:

1. Time zones, Qonversion uses UTC time;
2. FX rates.

***

What’s Next

Other Attribution Platforms

* [User Identifiers](user-identifiers)
* [Amplitude](amplitude)
* [Webhooks](webhooks)


# App Store Offer Codes
Source: https://documentation.qonversion.io/docs/appstore-offer-codes

Implement Apple offer code redemption in your app using the Qonversion presentCodeRedemptionSheet API on iOS 14 and later.

## Redeeming Apple Offer Codes

Users on iOS 14 and iPadOS 14 and later can redeem offer codes on the App Store through a one-time code redemption URL or within your app if you’ve implemented the `presentCodeRedemptionSheet` API.

Apple recommends using offer codes directly in your app via a redemption sheet.

Present the Offer Code redemption sheet to allow your users to redeem Offer Codes.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().presentCodeRedemptionSheet()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] presentCodeRedemptionSheet]
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().presentCodeRedemptionSheet();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().presentCodeRedemptionSheet();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().PresentCodeRedemptionSheet();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().presentCodeRedemptionSheet();
  ```
</CodeGroup>

<Warning>
  ### Set up offer codes

  Set up the offer codes before testing. See the details on setting up offer codes [here](https://help.apple.com/app-store-connect/#/dev6a098e4b1).
</Warning>

## Handling Results

If you need to get the results immediately after a user enters a promo code, please check the [deferred purchases](deferred-purchases) documentation. If a promo code was successfully applied, `checkEntitlements()` returns the updated entitlements.

<Note>
  When a redeemed offer code applies to a Family Sharing-enabled subscription, the entitlement may be granted to a different family member. In that case `checkEntitlements()` on the redeeming device will not reflect the new entitlement. See [Apple Family Sharing](apple-family-sharing) for the family-aware entitlement model.
</Note>

***

[Apple App Store](apple-app-store)

[App Store Privacy](app-store-privacy)


# Asapty
Source: https://documentation.qonversion.io/docs/asapty

Send in-app subscription and purchases events to Asapty

## Requirements

Before setting up the integration with Asapty, ensure that you have configured integration with [Apple Search Ads](apple-search-ads) and can view events attributed to this media source on the dashboard.

## Configure Integration

1. Navigate to the integrations page in Qonversion and select [Asapty](https://dash.qonversion.io/app/integration/create?name=asapty).

2. Find Asapty ID and provide it to Qonversion integration.

3. Configure Global Event Preferences:

   * Send Revenue Properties: Leave this enabled to receive revenue values. Disable only if you do not require revenue data.
   * Send Sales as Proceed: Choose whether to send revenue values net of App Stores’ commission (default) or gross.
   * Send Sandbox Events: Activate this toggle if you wish to receive sandbox events during testing.

<img alt="" />

4. Fine-Tune Event Settings: For each event, click More options to configure specific settings:

   * Enable Event: Toggle on to include the event in this integration. Turn it off if you do not need it.
   * Send Revenue: Enable or disable sending revenue for this particular event.

<img alt="" />

5. Save Your Configuration: Ensure that all settings are as desired and click Add new integration+/ Save to apply.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Asapty account.
</Check>

<Info>
  ### Notes

  1. You must repeat these steps for each app connected to Asapty.
  2. Qonversion only supports sending In-App events from users attributed with Apple Search Ads. Install postbacks are not supported.
</Info>

***

[AppsFlyer](appsflyer)

[Branch](branch)


# Awards
Source: https://documentation.qonversion.io/docs/awards

Award badge templates showcasing App Store recognition and achievements. These components build trust by highlighting your app's accolades and editorial features.

All Award templates support:

* **App Store styling** — authentic Apple-inspired designs
* **Full customization** — colors, text, images
* **Multiple formats** — banners, tiles, and cards

***

## Wide Banners

Full-width award banners for prominent placement.

### Apps You Need This Week

A wide banner featuring the "Apps You Need This Week" App Store editorial style.

<img alt="" />

**Features:**

* Full-width banner layout
* App Store editorial styling
* App icon placeholder
* "Apps You Need" branding

**Use for:**

* Hero sections on paywalls
* Above-the-fold trust indicators
* Featured app highlights

***

### App of the Day

A wide banner showcasing "App of the Day" recognition.

<img alt="" />

**Features:**

* "App of the Day" title treatment
* App icon and name display
* Gradient background option
* Premium visual styling

**Use for:**

* Main award showcase
* Paywall hero sections
* Trust-building headers

***

## Tiles

Compact square award badges.

### App of the Day Tile

A compact tile format for "App of the Day" recognition.

<img alt="" />

**Features:**

* Square tile format
* App Store icon styling
* Compact footprint
* Date display option

**Use for:**

* Sidebar placements
* Grid layouts
* Compact trust indicators

***

## Sharp Cards

Card-style awards with sharp corners and professional styling.

### Design Award Light

Apple Design Award card with light theme.

<img alt="" />

**Features:**

* Light background
* Apple Design Award styling
* Year badge
* Professional card design

**Use for:**

* Design-focused apps
* Premium app presentations
* Light-themed paywalls

***

### Design Award Dark

Apple Design Award card with dark theme.

<img alt="" />

**Features:**

* Dark background
* Apple Design Award styling
* Contrast text treatment
* Elegant dark mode design

**Use for:**

* Dark-themed apps
* Premium presentations
* Night mode paywalls

***

## Colored Banners

Vibrant award banners with accent backgrounds.

### App of the Year

A celebratory banner for "App of the Year" recognition.

<img alt="" />

**Features:**

* Bold accent background
* "App of the Year" title
* Premium visual treatment
* High-impact styling

**Use for:**

* Major award highlights
* Celebration screens
* Premium upgrade prompts

***

### Apps You Need Yellow

A vibrant yellow banner in the "Apps You Need" style.

<img alt="" />

**Features:**

* Bright yellow background
* High contrast text
* App Store editorial style
* Attention-grabbing design

**Use for:**

* Promotional sections
* Feature highlights
* Eye-catching trust indicators

***

## Customization

After adding an Award template, you can customize:

**Content:**

* Award title and subtitle
* App name and description
* Date or year display
* App icon image

**Styling:**

* Background colors and gradients
* Text colors and typography
* Border radius and shadows
* Icon size and positioning

***

## Best Practices

* **Be authentic** — only display awards your app has actually received
* **Use sparingly** — one prominent award badge is more effective than many
* **Match context** — use App Store awards for iOS users, Play Store for Android
* **Position strategically** — place near CTAs to boost conversion
* **Keep it current** — highlight recent awards over older ones
* **Combine with reviews** — pair awards with star ratings for maximum trust
* **Respect guidelines** — follow Apple's and Google's trademark guidelines

<Info>
  Ensure you have actually received the award before displaying it. Falsely claiming awards violates App Store guidelines and damages user trust.
</Info>

***

***

[Feature List](feature-list)

[AI Image Generation](ai-image-generation)


# Branch
Source: https://documentation.qonversion.io/docs/branch

Send iOS and Android in-app subscription events to Branch with Qonversion.

Qonversion can automatically send every valuable mobile subscription event to your Branch account to help you measure the marketing performance. Measure what drives your revenue by tracking trial-to-paying-user conversion, subscription renewals, refunds, and other useful subscription events.

## 1. Set up the SDKs

1. Make sure you have Branch SDK installed. If you do not have Branch integration yet, please use this documentation for [iOS](https://help.branch.io/developers-hub/docs/ios-sdk-overview) and [Android](https://help.branch.io/developers-hub/docs/android-sdk-overview).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

## 2. Identify user

**If your application includes user authentication**, it's important to link events sent from Qonversion with events received from the Branch SDK. This can be achieved by assigning the same user identifier to both Branch and Qonversion SDKs, as detailed in the [User Identifiers guide](user-identifiers#2-user-id-for-third-party-integrations). Below are the code snippets for various platforms to initialize the Branch SDK with the user ID:

<CodeGroup>
  ```swift Swift theme={null}
  // Initialize Branch SDK with the user ID
  Branch.getInstance().setIdentity("yourSideUserID")

  // Logout
  Branch.getInstance().logout()
  ```

  ```objectivec Objective-C theme={null}
  [[Branch getInstance] setIdentity:@"yourSideUserID"];

  // Logout
  [[Branch getInstance] logout];
  ```

  ```java Java theme={null}
  Branch.getInstance().setIdentity("yourSideUserID");

  // Logout 
  Branch.getInstance().logout();
  ```

  ```kotlin Kotlin theme={null}
  Branch.getInstance().setIdentity("yourSideUserID")

  // Logout
  Branch.getInstance().logout()
  ```
</CodeGroup>

<Warning>
  ### Do not track any purchase events on the client side

  Qonversion tracks all revenue events so if you track revenue events with Branch SDK, you may double count the revenue in your Branch account.
</Warning>

## 3. Configure the Branch Integration

## Provide Integration Details

1. Get your **Branch Key** from [Branch Settings Dashboard](https://dashboard.branch.io/account-settings/app)

2. Navigate to the Integrations section in your Qonversion project, select [Branch](https://dash.qonversion.io/app/integration/branch), and provide the **Branch Key** and Save.

<img alt="" />

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Branch account.
</Check>

## 4. Check the integration

Qonversion sends all events as "Purchase" with a custom event alias to Branch. The event names that you set in Qonversion dashboards are the aliases. To see the events from Qonversion in Branch:

* navigate to the Summary dashboard in Branch
* filter PURCHASE events with the "show" filter
* use the additional filter below the chart: "custom\_event\_alias" equals to the event name you set in Qonversion (e.g. trial\_started)

## 5. Countries events attribution

Branch attributes all server events to the country where the server sending these events is located. The only way to change this and attribute events to users' countries is to contact Branch support. You should contact branch support with the request to whitelist your app (include your app's Branch ID in the communication) to record users' IP address instead of the server IP address.

## Event Payload

In case you need details about data sent to Branch, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "branch_key":"key_live_KEY",
     "name":"PURCHASE",
     "customer_event_alias":"trial_converted",
     "user_data":{
        "os":"",
        "developer_identity":"",
        "idfa":""
     },
     "event_data":{
        "transaction_id":"",
        "currency":"EUR",
        "revenue":2.39
     }
  }
  ```
</CodeGroup>

**→[Read more about tracked events here](integrations-overview#tracked-events)**

***

[Asapty](asapty)

[Braze](braze)


# Braze
Source: https://documentation.qonversion.io/docs/braze

Automatically send Qonversion in-app subscription and purchase events to Braze for customer engagement, messaging, and analytics.

With Qonversion, you can automatically send in-app subscription and purchases events to Braze.

## 1. Set up the SDKs

1. Make sure you have Braze SDK installed. If you do not have Braze integration yet, please use this documentation for [iOS](https://www.braze.com/docs/developer_guide/platform_integration_guides/ios/initial_sdk_setup/) and [Android](https://www.braze.com/docs/developer_guide/platform_integration_guides/android/initial_sdk_setup/android_sdk_integration/).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Attribute events sent from Qonversion and events received from the Braze SDK to the same user by setting the same user id to Braze that you set to Qonversion SDK in [User Identifiers guide](user-identifiers#2-user-id-for-third-party-integrations).

<CodeGroup>
  ```swift Swift theme={null}
  Braze.shared.changeUser(userId: "yourSideUserID")
  ```

  ```objectivec Objective-C theme={null}
  [braze changeUser:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  Braze.getInstance(this).changeUser("yourSideUserID");
  ```

  ```kotlin Kotlin theme={null}
  Braze.getInstance(this).changeUser("yourSideUserID")
  ```
</CodeGroup>

<Info>
  These snippets use the modern `Braze` class. If your app is still on the legacy `Appboy` SDK, the equivalent call is `Appboy.sharedInstance()?.changeUser("yourSideUserID")` - update to `Braze` when you bump the SDK.
</Info>

## 2. Configure the Braze Integration

## Provide Integration Details

1. Get your **Braze API key** and your **Braze instance** from [Braze](https://dashboard-01.braze.com/).

2. Navigate to the Integrations section in your Qonversion project, select [Braze](https://dash.qonversion.io/app/integration/braze), and provide the **Braze API key** and your **Braze instance**, and Save.

<img alt="" />

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Braze account.
</Check>

## Event Payload

In case you need details about data sent to Braze, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "events":[
        {
           "external_id":"638e041drd467600318edd46",
           "name":"subscription_renewed",
           "properties":{
              "revenue":99,
              "storefront":"USA"
           },
           "time":"2023-06-14T12:20:36+00:00"
        }
     ]
  }
  ```
</CodeGroup>

***

[Branch](branch)

[CleverTap](clevertap)


# Capacitor
Source: https://documentation.qonversion.io/docs/capacitor

Install Qonversion Capacitor Plugin to validate user receipts, and get in-app subscription analytics and third-party integrations.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/capacitor-plugin?label=Latest%20Release)](https://github.com/qonversion/capacitor-plugin/releases)

## Install via npm

Qonversion Plugin package is available on [npm](https://www.npmjs.com/package/@qonversion/capacitor-plugin).

<CodeGroup>
  ```bash theme={null}
  npm install @qonversion/capacitor-plugin
  ```
</CodeGroup>

After installing, sync the plugin into your iOS and Android projects so the native code is wired up:

<CodeGroup>
  ```bash theme={null}
  npx cap sync
  ```
</CodeGroup>

## Kids Mode for Qonversion Capacitor Plugin

In case you are building an App for Kids, [follow this guide](kids-mode-sdk) to learn about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# Carousels
Source: https://documentation.qonversion.io/docs/carousels

Carousel templates provide swipeable, multi-slide layouts for showcasing content in an engaging, interactive format. Use carousels for onboarding flows, feature highlights, category navigation, and visual galleries.

All Carousel templates support:

* **Autoplay** — automatic slide advancement with configurable delay
* **Touch navigation** — swipeable on mobile devices
* **Loop mode** — infinite scrolling option
* **Pagination** — optional navigation dots
* **Extended overflow** — slides visible beyond container edges

***

### Tape Carousel

A compact, tag-style carousel with icon and uppercase label pairs. Ideal for category navigation or feature highlights with a modern, minimal design.

<img alt="" />

**Features:**

* Icon + text tag design
* Multiple slides visible simultaneously
* Infinite loop enabled
* No pagination dots
* Compact, badge-like appearance

**Use for:**

* Category selection (e.g., Cycling, Swimming, Yoga)
* Feature tags or highlights
* Quick navigation options

***

### Gallery Carousel

A full-width image carousel with large, bold headings overlaid on background images. Perfect for visual storytelling and immersive content presentation.

<img alt="" />

**Features:**

* Full-screen background images
* Large heading text overlay
* Internal pagination dots
* Centered slide focus
* Autoplay with smooth transitions

**Use for:**

* Onboarding flows with visual impact
* Feature showcases with imagery
* Brand storytelling sequences
* Hero sections with rotating content

***

### Cards Carousel

Colorful cards with titles displayed above each card, featuring images and descriptive text. Great for categorized content like age groups, skill levels, or product tiers.

<img alt="" />

**Features:**

* Title positioned outside (above) the card
* Colored background containers
* Image area with flexible sizing
* Heading and description text
* Multiple cards visible with peek effect
* Equal height slides

**Use for:**

* Age group or tier selection
* Category browsing with descriptions
* Product or plan comparisons
* Educational content organization

***

### Reviews Carousel

A horizontal carousel displaying customer reviews with star ratings, testimonial text, and author names. Perfect for showcasing positive feedback and building trust before purchase decisions.

<img alt="" />

**Features:**

* 5-star rating display
* Review text with automatic wrapping
* Author name attribution
* External pagination dots
* Autoplay with 3-second default interval
* Centered slides with peek effect

**Use for:**

* Testimonial sections on paywalls
* Customer feedback highlights
* Trust-building before purchase decisions

<Info>
  Also available in [Social Proof](social-proof) category.
</Info>

***

### Products Slider

A horizontal carousel of product cards with optional badges, pricing, descriptions, and CTA buttons. Ideal for showcasing multiple subscription options in a swipeable format.

<img alt="" />

**Features:**

* Swipeable product cards
* Optional "Best Value" or promotional badges
* Price and description display
* CTA button per product
* Automatic select-product state handling
* Autoplay with configurable timing

**Use for:**

* Multiple subscription tier comparison
* Promotional offer showcases
* Plan browsing with detailed cards

<Info>
  Also available in [Product Blocks](product-blocks) category.
</Info>

***

### Carousel Properties Reference

| Property            | Description                      | Default            |
| ------------------- | -------------------------------- | ------------------ |
| **Slides Per View** | Number of slides visible at once | Varies by template |
| **Space Between**   | Gap between slides (px)          | 15                 |
| **Autoplay Delay**  | Seconds between transitions      | 3                  |
| **Loop**            | Enable infinite scrolling        | Template-specific  |
| **Centered**        | Center the active slide          | Template-specific  |
| **Pagination**      | Show navigation dots             | Template-specific  |
| **Extended**        | Show slides beyond container     | Template-specific  |

***

### Customization

After adding a carousel template, you can customize:

**Slides:**

* Add or remove slides
* Edit slide content (text, images, icons)
* Adjust individual slide styling

**Layout:**

* Change slides per view
* Adjust spacing between slides
* Enable/disable centering

**Behavior:**

* Set autoplay speed or disable
* Toggle loop mode
* Show/hide pagination

**Styling:**

* Background colors
* Typography (fonts, sizes, colors)
* Border radius and shadows
* Padding and margins

***

### Best Practices

* **Limit slide count** — 3-5 slides optimal for engagement
* **Use consistent styling** — maintain visual harmony across slides
* **Keep content scannable** — users swipe quickly, make each slide count
* **Test autoplay timing** — ensure users have time to read content
* **Consider touch targets** — make interactive elements easy to tap
* **Preview on devices** — test carousel behavior on different screen sizes

***

***

[Social Proof](social-proof)

[CTA Buttons](cta-buttons)


# How to check user entitlements
Source: https://documentation.qonversion.io/docs/check-permissions

Check a user's entitlements with the checkEntitlements method of the Qonversion SDK to gate access to premium features, read the renewal state, and inspect the Entitlement and Transaction objects.

An entitlement is access to the premium features of your application. Check a user's entitlements with the `checkEntitlements()` method to decide what premium content to unlock. Read more about creating and using entitlements in [Entitlements](entitlements).

Call `checkEntitlements()` at app launch to see whether a user has the entitlement you require. The method validates the user's receipt and returns the current entitlements.

Qonversion can also manage cross-platform entitlements through the [user Identity concept](user-identifiers#3-user-identity): for example, after a user subscribes in your iOS app, you can check the same entitlements in your Android or web apps.

<Info>
  The Qonversion SDK [caches product and entitlement data](offline-sdk-mode), so entitlements are still available immediately when the internet connection is lost or the server is delayed.
</Info>

<Warning>
  An entitlement object is returned only if the user has made a purchase, or you granted the entitlement manually through [the Customer tab](customers#edit-entitlements) or the Grant Entitlement API. Otherwise `checkEntitlements()` returns an empty result — an empty result means the user has no entitlements, not an error.
</Warning>

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().checkEntitlements { (entitlements, error) in
    if let error = error {
      // handle error
      return
    }
    
    if let premium: Qonversion.Entitlement = entitlements["premium"], premium.isActive {
      switch premium.renewState {
        case .willRenew, .nonRenewable:
          // .willRenew is the state of an auto-renewable subscription 
          // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
          break
        case .billingIssue:
          // Grace period: entitlement is active, but there was some billing issue.
          // Prompt the user to update the payment method.
          break
        case .cancelled:
          // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
          // Prompt the user to resubscribe with a special offer.
          break
        default: break
      }
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] checkEntitlements:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull entitlements,
                                  NSError * _Nullable error) {
      QONEntitlement *premiumEntitlement = entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        switch (premiumEntitlement.renewState) {
          case QONEntitlementRenewStateWillRenew:
          case QONEntitlementRenewStateNonRenewable:
            // QONEntitlementRenewStateWillRenew is state for auto-renewable purchases
            // QONEntitlementRenewStateNonRenewable is state for in-app purchases that unlock the entitlement lifetime
            break;
          case QONEntitlementRenewStateBillingIssue:
            // Grace period: entitlement is active, but there was some billing issue.
            // Prompt the user to update the payment method.
            break;
          case QONEntitlementRenewStateCancelled:
            // The user canceled the subscription, but the subscription has not expired yet.
            // Prompt the user to resubscribe with some special offer.
            break;
          default:
            break;
        }
      }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().checkEntitlements(new QonversionEntitlementsCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
          final QEntitlement premiumEntitlement = entitlements.get("premium");

          if (premiumEntitlement != null && premiumEntitlement.isActive()) {
              // handle active entitlement here

              // also you can check renew state if needed
              // for example to check if user has canceled subscription and offer him a discount
              switch (premiumEntitlement.getRenewState()) {
                  case NonRenewable:
                      // NonRenewable is the state of a consumable or non-consumable in-app purchase
                      break;
                  case WillRenew:
                      // WillRenew is the state of an auto-renewable subscription
                      break;
                  case BillingIssue:
                      // Prompt the user to update the payment method.
                      break;
                  case Canceled:
                      // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                      // Prompt the user to resubscribe with a special offer.
                      break;
                  default: break;
              }
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.checkEntitlements(object: QonversionEntitlementsCallback {
      override fun onSuccess(entitlements: Map<String, QEntitlement>) {
          val premiumEntitlement = entitlements["premium"]
          if (premiumEntitlement != null && premiumEntitlement.isActive) {
              // handle active entitlement here

              // also you can check renew state if needed
              // for example to check if user has canceled subscription and offer him a discount
              when (premiumEntitlement.renewState) {
                  QEntitlementRenewState.NonRenewable -> {
                      // NonRenewable is the state of a consumable or non-consumable in-app purchase
                  }
                  QEntitlementRenewState.WillRenew -> {
                      // WillRenew is the state of an auto-renewable subscription
                  }
                  QEntitlementRenewState.BillingIssue -> {
                      // Prompt the user to update the payment method.
                  }
                  QEntitlementRenewState.Canceled -> {
                      // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                      // Prompt the user to resubscribe with a special offer.
                  }
                  else -> {

                  }
              }
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().checkEntitlements();
    final premium = entitlements['premium'];
    if (premium != null && premium.isActive) {
      switch (premium.renewState) {
        case QEntitlementRenewState.willRenew:
        case QEntitlementRenewState.nonRenewable:
        // .willRenew is the state of an auto-renewable subscription
        // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
          break;
        case QEntitlementRenewState.billingIssue:
        // Grace period: entitlement is active, but there was some billing issue.
        // Prompt the user to update the payment method.
          break;
        case QEntitlementRenewState.canceled:
        // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
        // Prompt the user to resubscribe with a special offer.
          break;
        default:
          break;
      }
    }
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
      switch (premiumEntitlement.renewState) {
        case EntitlementRenewState.NON_RENEWABLE:
          // NON_RENEWABLE is the state of consumable/non-consumable IAPs that could unlock lifetime access
          break;
        case EntitlementRenewState.WILL_RENEW:
          // WILL_RENEW is the state of an auto-renewable subscription
          break;
        case EntitlementRenewState.CANCELED:
          // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
          // Prompt the user to resubscribe with a special offer.
          break;
        case EntitlementRenewState.BILLING_ISSUE:
          // Grace period: entitlement is active, but there was some billing issue.
          // Prompt the user to update the payment method.
          break;
        case EntitlementRenewState.UNKNOWN:
          // We were unable to determine subscription renew state
          break;
      }
    }
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
  {
      if (error == null)
      {
          if (entitlements.TryGetValue("premium", out Entitlement premium) && premium.IsActive)
          {
              switch(premium.RenewState)
              {
                  case QEntitlementRenewState.WillRenew:
                  case QEntitlementRenewState.NonRenewable:
                      // .willRenew is the state of an auto-renewable subscription 
                      // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
                      break;
                  case QEntitlementRenewState.BillingIssue:
                      // Grace period: entitlement is active, but there was some billing issue.
                      // Prompt the user to update the payment method.
                      break;
                  case QEntitlementRenewState.Canceled:
                      // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                      // Prompt the user to resubscribe with a special offer.
                      break;
                  default:
                      break;
              }
          }
      }
      else
      {
          // Handle the error  
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

      const premiumEntitlement = entitlements.get('premium');
      if (premiumEntitlement != null) {
          switch (premiumEntitlement.renewState) {
              case Qonversion.EntitlementRenewState.NON_RENEWABLE:
                  // NON_RENEWABLE is the state of consumable/non-consumable IAPs that could unlock lifetime access
                  break;
              case Qonversion.EntitlementRenewState.WILL_RENEW:
                  // WILL_RENEW is the state of an auto-renewable subscription
                  break;
              case Qonversion.EntitlementRenewState.CANCELED:
                  // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
                  // Prompt the user to resubscribe with a special offer.
                  break;
              case Qonversion.EntitlementRenewState.BILLING_ISSUE:
                  // Grace period: entitlement is active, but there was some billing issue.
                  // Prompt the user to update the payment method.
                  break;
              case Qonversion.EntitlementRenewState.UNKNOWN:
                  // We were unable to determine subscription renew state
                  break;
          }
      }
  } catch (e) {
      // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
      switch (premiumEntitlement.renewState) {
        case EntitlementRenewState.NON_RENEWABLE:
          // NON_RENEWABLE is the state of consumable/non-consumable IAPs that could unlock lifetime access
          break;
        case EntitlementRenewState.WILL_RENEW:
          // WILL_RENEW is the state of an auto-renewable subscription
          break;
        case EntitlementRenewState.CANCELED:
          // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
          // Prompt the user to resubscribe with a special offer.
          break;
        case EntitlementRenewState.BILLING_ISSUE:
          // Grace period: entitlement is active, but there was some billing issue.
          // Prompt the user to update the payment method.
          break;
        case EntitlementRenewState.UNKNOWN:
          // We were unable to determine subscription renew state
          break;
      }
    }
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

## The Entitlement object

Each value in the `entitlements` map is an `Entitlement` object with the following fields.

| Field                    | Type / values                                                            | Description                                                                                                                                                                                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | String                                                                   | Qonversion entitlement ID. For example, `premium`.                                                                                                                                                                                                                                                       |
| `isActive`               | Boolean                                                                  | `true` means the user has an active entitlement. `isActive = true` does not mean the subscription will renew — a user can have an active entitlement while auto-renewal is switched off.                                                                                                                 |
| `source`                 | Enum: `appstore`, `playstore`, `stripe`, `manual`, `unknown`             | Source via which the entitlement was activated: `appstore` — App Store; `playstore` — Play Store; `stripe` — Stripe; `manual` — activated manually; `unknown` — source could not be detected.                                                                                                            |
| `startedDate`            | Date                                                                     | Initial transaction date. For a subscription with a trial period, this is when the trial starts.                                                                                                                                                                                                         |
| `trialStartDate`         | Date, or `null`                                                          | The trial start date for the current entitlement. `null` for an entitlement unlocked by a consumable/non-consumable/lifetime purchase or a subscription without a trial.                                                                                                                                 |
| `firstPurchaseDate`      | Date                                                                     | The date of the first purchase.                                                                                                                                                                                                                                                                          |
| `lastPurchaseDate`       | Date                                                                     | The date of the last purchase.                                                                                                                                                                                                                                                                           |
| `autoRenewDisableDate`   | Date                                                                     | The date when auto-renew for the subscription was disabled.                                                                                                                                                                                                                                              |
| `expirationDate`         | Date, or `null`                                                          | The expiration date for a subscription. `null` for a consumable/non-consumable in-app purchase or a lifetime subscription.                                                                                                                                                                               |
| `productId`              | String                                                                   | Identifier of the product from the Qonversion dashboard.                                                                                                                                                                                                                                                 |
| `renewState`             | Enum: `nonRenewable`, `willRenew`, `billingIssue`, `canceled`, `unknown` | Renewal state of the subscription: `nonRenewable` — consumable or non-consumable in-app purchase; `willRenew` — subscription is active and auto-renew is on; `billingIssue` — there was a billing issue; `canceled` — the subscription was canceled; `unknown` — no information about the renewal state. |
| `renewsCount`            | Integer                                                                  | Subscription renews count for the entitlement. Counting starts from the second paid transaction. Example: with 20 transactions — the first is the trial-started transaction, the second is the first paid transaction (trial converted), and the remaining 18 are renewals, so `renewsCount` is 18.      |
| `grantType`              | Enum: `purchase`, `familySharing`, `offerCode`, `manual`                 | How the entitlement was granted: `purchase` — the user bought a subscription; `familySharing` — via family sharing; `offerCode` — using an offer code; `manual` — via the Qonversion dashboard.                                                                                                          |
| `lastActivatedOfferCode` | String                                                                   | The last activated offer code that unlocks the current entitlement.                                                                                                                                                                                                                                      |
| `transactions`           | Array of `Transaction`                                                   | Transactions that unlocked the current entitlement.                                                                                                                                                                                                                                                      |

## The Transaction object

Each element of the `transactions` array is a `Transaction` object with the following fields.

| Field                       | Type / values                                                                                                               | Description                                                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `originalTransactionId`     | String                                                                                                                      | The original transaction identifier.                                                                                                      |
| `transactionId`             | String                                                                                                                      | The transaction identifier.                                                                                                               |
| `offerCode`                 | String                                                                                                                      | The offer code used to get the transaction.                                                                                               |
| `transactionDate`           | Date                                                                                                                        | The date of the transaction.                                                                                                              |
| `expirationDate`            | Date, or `null`                                                                                                             | The expiration date for the transaction. `null` for a consumable/non-consumable in-app purchase or a lifetime subscription.               |
| `transactionRevocationDate` | Date                                                                                                                        | The date the transaction was revoked. Set when the App Store refunds a transaction or revokes it from family sharing.                     |
| `environment`               | Enum: `sandbox`, `production`                                                                                               | The environment of the transaction.                                                                                                       |
| `ownershipType`             | Enum: `owner`, `familySharing`                                                                                              | Ownership of the transaction: `owner` — the user owns the transaction; `familySharing` — the user got the transaction via family sharing. |
| `type`                      | Enum: `subscriptionStarted`, `subscriptionRenewed`, `trialStarted`, `introStarted`, `introRenewed`, `nonConsumablePurchase` | The type of the transaction.                                                                                                              |


# CleverTap
Source: https://documentation.qonversion.io/docs/clevertap

Send in-app subscription events to CleverTap to engage and win back your subscribers

Connect CleverTap account to Qonversion to launch user engagement campaigns, win back your customers, or reach them out when they have billing issues. After the connection is complete, Qonversion will be sending all the [subscription events](integrations-overview#tracked-events) to CleverTap.

To run the integration, follow the steps below.

## 1. Setup the SDKs

1. Make sure you have CleverTap SDK installed. Check the official CleverTap SDK documentation [here](https://developer.clevertap.com/docs/clevertap-sdks).
2. Set Qonversion SDK following [Installing the SDKs guides](install-sdk).
3. Send *yourSideUserId* to Qonversion using [Custom User Properties](user-properties#optional-set-user-id).

## 2. Configure the CleverTap Integration

1. Open the CleverTap dashboard using your region-based URL and log in:

   * [India](https://in1.dashboard.clevertap.com/login.html)
   * [Singapore](https://sg1.dashboard.clevertap.com/login.html)
   * [United States](https://us1.dashboard.clevertap.com/login.html)
   * [Indonesia](https://aps3.dashboard.clevertap.com/login.html)
   * [Middle East (UAE)](https://mec1.dashboard.clevertap.com/login.html)
   * [Europe (default region)](https://eu1.dashboard.clevertap.com/login.html)

2. Navigate to the *Settings* page by clicking the gear icon in the bottom left navigation panel and selecting Settings dashboard.

<img alt="" />

3. Copy values from the *Project ID* and *Passcode* fields. We will need this information in the following steps.

<img alt="" />

4. Navigate to the *Tools → Integrations* section in your [Qonversion account](https://dash.qonversion.io/)
5. Choose your platform (IOS or Android), click the *Add new +* button, and select **CleverTap**
6. Provide the **Project ID** and **Passcode** copied during the fourth step above to the corresponding fields

<img alt="" />

7. Choose your CleverTap account region

<img alt="" />

8. Click **Save** or **Add new integration**
9. Congratulations! Now Qonversion will be sending all the [subscription events](integrations-overview#tracked-events) to your CleverTap account.

## Event Payload

In case you need details about data sent to CleverTap, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "d":[
        {
           "identity":"", //Unique user identifier set by the app owner
           "ts":1686891155,
           "type":"event",
           "evtName":"subscription_renewed",
           "evtData":{
              "id":000000000,
              "platform":"iOS",
              "ip":"000.000.00.0",
              "product_id":"product_id",
              "quantity":1,
              "transaction_id":"2000000456329567",
              "country":"TR",
              "storefront":"USA",
              "app_version":"1.0",
              "os_name":"iOS",
              "os_version":"16.4.1",
              "device_model":"iPhone 11",
              "device_id":"",
              "revenue":1049.993,
              "currency":"TRY"
           }
        }
     ]
  }
  ```
</CodeGroup>

***

[Braze](braze)

[Facebook Ads](facebook)


# Cohorts
Source: https://documentation.qonversion.io/docs/cohorts

Cohort analytics allows you to see a complete picture of how your subscriptions evolve over their lifetime

In Qonversion, you can analyse your cohorts' progression using the following metrics: Revenue Retention and Subscriber Retention.

## Revenue

### 1. Net Revenue Retention

* The first two columns show the month and the initial revenue (net of refunds) from customers who installed the app in the corresponding month.

* Column 0 shows the initial cohort's revenue (net of refunds), calculated as a sum of Subscription Started and Trial Converted Event.

* The following columns (1, 2, 3, etc.) represent the number of **consecutive renewal periods** since the customers subscribed (months for a monthly subscription, weeks for a weekly subscription, etc.).

* The last column shows the total revenue from the corresponding cohort of users.

<Frame>
  <img />
</Frame>

### 2. Subscriber Retention and ARPPU

* The first two columns show the month and the initial number of paying customers who installed the app in that month.

* Column 0 shows the initial number of customers who converted to paying after the app was installed.

* The columns (1, 2, 3, etc.) represent the number of **consecutive renewal periods** since the customers subscribed (months for a monthly subscription, weeks for a weekly subscription, etc.).

* The last column shows the ARP(P)U - Average Revenue Per (Paying) User. It is calculated as the cohort's cumulative revenue divided by the number of subscribers at its start. In other words, ARPPU is the actual historic LTV of your subscribers.

<Frame>
  <img />
</Frame>

### 3. Include the Current Month Data

You can choose to include or exclude the current month's data. If the current month switch is on, you will see the current month cohort data, and all previous cohorts will include the subscription renewals that happened during the current month. Since the current month is still ongoing, the last period's retention values typically will appear to be lower. That will also affect average retention numbers.

<img alt="" />

***

[Events](events-analytics)

[Integrations](integrations-overview)


# Components
Source: https://documentation.qonversion.io/docs/components

Every screen in the No-Code Builder is made up of components — reusable, modular elements that define structure, content, and behavior.

You can combine components freely to build anything from a single-page paywall to a multi-screen onboarding flow.

Each component supports a unique set of properties, which can be configured in the Right Panel. Below you’ll find an overview of all available components, grouped by category, with quick links to their common use cases and key properties.

***

## Components Reference Table

| Component       | Parent | Actions | Description                                                                | Function                                                 |
| --------------- | ------ | ------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Container**   | ✅      | ✅       | Core layout block that groups and aligns other components.                 | Organizes and structures multiple elements               |
| **Button**      | ✅      | ✅       | A clickable call-to-action element                                         | Triggers a purchase attempt or other action              |
| **Product**     | ✅      | ✅       | Displays a selectable product with customizable styling                    | Showcases in-app purchases or subscriptions              |
| **Heading**     | ❌      | ❌       | Text block for titles using the /h1 tag                                    | Adds main headings or key messages                       |
| **Text**        | ❌      | ❌       | Text block for descriptions, disclaimers, or variables using the /p tag    | Adds body text, descriptions, or instructions            |
| **Toggle**      | ❌      | ✅       | Switch element for selecting between two states (e.g., Monthly vs. Yearly) | Changes product selection                                |
| **Tabs**        | ✅      | ❌       | Segmented layout component for switching between different content states  | Enables navigation between grouped sections              |
| **Tab**         | ✅      | ❌       | Child element inside Tabs                                                  | Holds content for a single tab view                      |
| **Badge**       | ✅      | ✅       | Styled tag for emphasis (e.g., “Best Value,” “Limited Offer”).             | Highlights products, offers, or section                  |
| **Image/GIF**   | ❌      | ❌       | Displays static or animated visuals                                        | Adds images or GIFs to enhance visual design.            |
| **Icon**        | ❌      | ✅       | Small decorative or functional icon element                                | Adds visual cues, or can be used as a **closing** button |
| **Lottie**      | ❌      | ❌       | Vector animation file with dynamic scaling                                 | Adds lightweight animations or motion effects            |
| **Video**       | ❌      | ❌       | Embeddable video player                                                    | Displays product demos or looping backgrounds            |
| **Slider**      | ✅      | ❌       | Parent container that holds multiple Slides                                | Enables swipeable multi-page content                     |
| **Slide**       | ✅      | ❌       | Child component inside a Slider                                            | Holds elements within each swipeable section             |
| **Quiz**        | ✅      | ❌       | Parent container for quiz layouts with selectable options                  | Captures user input or preferences in onboarding flows   |
| **Star Rating** | ❌      | ❌       | Display-only star rating element with partial-fill support                 | Shows ratings on social-proof and review templates       |
| **Header**      | ✅      | ❌       | Pre-built top section with standard layout and styling.                    | Used for consistent screen headers                       |
| **Footer**      | ✅      | ❌       | Pre-built bottom section with standard layout and styling.                 | Used for CTAs, legal text, or navigation.                |

<Info>
  **Parent Components** can contain other elements inside them.

  * Actions include functions like **Make Purchase**, **Open URL**, **Go to Page**, or **Select Product** and more.
  * Components can be freely combined to create custom layouts.
</Info>

***

## Layout Components

### Container

The **Container** is the foundational layout block in the **Builder**. It’s used to group and align multiple elements and can be nested inside other containers for flexible layout control.

**Use cases:**

* Creating columns, cards, or grouped sections
* Holding text, buttons, and images together
* Structuring responsive paywall layouts

**Key properties:**

* Action
* Layout (direction, distribution, wrap, gap)
* Alignment
* Position (static, relative, absolute, fixed, sticky)
* Size (fill, fit, auto, fixed)
* Spacing (margin, padding)
* Background, Border, Shadow
* Selected State (if linked to product)

<Info>
  **Tip:** Use containers as “cards” for product blocks or grouped pricing sections.
</Info>

<Frame>
  <img />
</Frame>

***

### Header / Footer (Pre-Built)

Pre-designed layout sections that maintain consistent structure across screens.

* **Header**: Ideal for app logos, titles, or progress indicators.
* **Footer**: Perfect for CTAs, purchase buttons, or legal text.

**Important:**

* You can add only **one** **Header** and **one** **Footer** per screen.
* Both are placed automatically at the top and bottom of the layout.
* Their main property is **Positioning**, which is **Static** — they remain anchored in their respective places and do not scroll independently.

**Key properties:**

* **Alignment** – controls horizontal content placement (Start, Center, End).
* **Padding / Background** – adjust internal spacing and visual styling.
* **Typography** – inherit or override font family, weight, and color for text elements.
* **Static Position** – ensures Header and Footer stay fixed to screen boundaries (not scrollable).

<img alt="" />

***

### Slider

A horizontal parent container used to create swipeable multi-step experiences.

**Use for:**

* Onboarding flows
* Multi-card offers or tutorials

**Key properties:**

* Direction (horizontal)
* Slide count
* Gap between slides

#### Slide

A single page inside a Slider. Each slide has independent content and styling.

**Use for:**

* Onboarding step
* Product card or information screen

**Key properties:**

* **Background**, **Padding**, **Layout**, **Typography**

<img alt="" />

***

### Tabs

A segmented layout component for switching between grouped content areas.

**Use for:**

* Switching between plans (Monthly, Annual, Lifetime)
* Segmenting features or pricing groups

**Key properties:**

* Tab Items (add / rename / reorder)
* Linked Containers or Product Groups
* Default Tab
* Orientation (horizontal / vertical)
* Active / Inactive styles

#### Tab

A single view or section within the Tabs component.

**Use for:**

* Each pricing plan or content block linked to a tab selection.

**Key properties:**

* Layout
* Padding / Margin
* Background

<img alt="" />

***

## Text & Display Components

### Heading

Large text element used for titles, section headers, or key messages.

**Use for:**

* Paywall headline (“Upgrade to Premium”)
* Onboarding step titles

**Key properties:**

* Typography (font, weight, color, size and more)
* Alignment
* Margin / Padding
* Variables (dynamic product data)

***

### Text

Smaller text element used for supporting details or variable-based descriptions.

**Use for:**

* Feature lists
* Descriptions and disclaimers
* Dynamic price or period text

**Key properties:**

* Typography (font, color, size)
* Alignment
* Variables (e.g., products.product\_id.price\_per\_month)
* Margin / Padding

***

### Badge

A small highlighted label that draws attention to offers or key information.

**Use for:**

* “Best Value” or “Most Popular” tags
* Promotional callouts

**Key properties:**

* Text content
* Style (solid / outline / soft)
* Color and background
* Border radius
* Alignment

<Info>
  **Note**: **Badge** can be attached only to container-based components.
</Info>

<img alt="" />

***

### Star Rating

Display-only element that renders a configurable star rating with partial-fill support. Useful as a standalone trust indicator or as the visual primitive behind every review template - see the [Social Proof](social-proof) category for ready-made templates that use it.

**Use for:**

* Inline rating badges in headers
* Trust indicators near CTAs
* Custom social-proof layouts

**Key properties:**

* **Rating** — value from 0-5, supports decimals (e.g., 4.9 renders as 4 full stars + 1 star at 90% fill)
* **Max Stars** — maximum number of stars to display
* **Size** — star size in pixels
* **Fill Color** — color for filled stars
* **Empty Color** — color for unfilled stars
* **Gap** — spacing between stars in pixels

***

## Interactive Components

### Button

Clickable call-to-action element that triggers an event or navigation.

Use for:

* “Continue”, “Subscribe”, or “Buy Now” actions
* Navigating between pages or screens

Key properties:

* Action (Make Purchase, Select Product, Open URL, Go to Page, Show Screen)
* Label text (supports variables)
* Size and alignment
* Background, Border, Shadow
* Typography (font, color, weight)

***

### Toggle

Switch component that changes between two or more states, commonly used for pricing options.

Use for:

* Monthly ↔ Yearly plan switchers
* Feature toggles

**Key properties:**

* Options (labels for each state)
* Default State
* Linked Products or Containers
* Action on Change
* Background and active/inactive text colors

<Info>
  Combine Toggles with Product Containers to dynamically update user selection. ***Changing Products on toggles is coming soon***
</Info>

<img alt="" />

***

### Quiz

Parent container that renders a list or grid of selectable options. Use it to capture user input during onboarding flows or to personalise the rest of a paywall based on the answer.

**Use for:**

* Onboarding questions ("What's your goal?", "How experienced are you?")
* Preference capture before showing a tailored paywall
* Multi-step quizzes that branch into different screens

**Available templates:**

* **Simple** — single-select list of plain options
* **Multiple choice** — multi-select list
* **Emoji** — list with leading emojis per option
* **Icons** — list with leading icons per option
* **Image tiles** — 2-column grid of image tiles

Each Quiz contains child **Quiz Option** elements; selected options switch to a highlighted state automatically.

**Key properties:**

* Layout (list, image-tiles)
* Template (simple, multiple-choice, emoji, icons, image-tiles)
* Selected/default option styling
* Background, Border, Padding
* Linked navigation action on each option (Go to Page, Show Screen)

***

## Product Components

### Product

A pre-built container displaying subscription or one-time purchase details. Automatically filled with data from your connected store.

**Use for:**

* Main product or subscription cards
* Price comparison layouts

**Key properties:**

* Linked Product
* Layout (vertical / horizontal)
* Badge support
* Product Variables (price, trial\_period, currency)
* Background, Border, Shadow
* Action (Select Product, Make Purchase)
* Selected State styling

<Info>
  **Tip**: Group multiple Product components in one Container for multi-plan layouts.
</Info>

<Frame>
  <img />
</Frame>

***

## Media Components

### Image / GIF

Displays static or animated visual content.

**Use for:**

* Product illustrations
* Onboarding artwork
* Decorative visuals

**Key properties:**

* Source (upload or URL)
* Fit (cover / contain)
* Border radius / shadows
* Alignment / Size
* Action (optional, e.g., Open URL)

***

### Lottie File

Vector-based animation file (.json) for smooth, scalable motion graphics.

**Use for:**

* Onboarding animations
* Success or loading states

**Key properties:**

* Loop / Autoplay toggle
* Playback speed
* Alignment / Size

<img alt="" />

***

### Icon

Simple decorative or functional symbol.

**Use for:**

* Feature checkmarks
* Navigation or visual cues

**Key properties:**

* Icon set and name
* Color and size
* Alignment

***

### Video

Embeddable video block for background loops or short product demos.

**Available properties:**

* Upload up to 150Mb
* Autoplay / Loop toggle
* Mute / Sound control
* Cover fit

***

#### Component Quick Reference

| **Component**   | **Purpose**                  | **Supports Actions** | **Has Children** |
| --------------- | ---------------------------- | -------------------- | ---------------- |
| Container       | Groups and aligns elements   | ✅                    | ✅                |
| Header / Footer | Standard layout sections     | ❌                    | ✅                |
| Slider          | Swipeable parent layout      | ❌                    | ✅                |
| Slide           | Page inside slider           | ❌                    | ✅                |
| Tabs            | Switchable segmented view    | ❌                    | ✅                |
| Tab             | Individual tab section       | ❌                    | ✅                |
| Heading         | Large text element           | ❌                    | ❌                |
| Text            | Description or dynamic value | ❌                    | ❌                |
| Badge           | Highlight tag                | ✅                    | ✅                |
| Button          | Interactive call-to-action   | ✅                    | ❌                |
| Toggle          | Multi-state switch           | ✅                    | ❌                |
| Quiz            | Selectable option container  | ❌                    | ✅                |
| Star Rating     | Display-only rating element  | ❌                    | ❌                |
| Product         | Pre-filled product card      | ✅                    | ✅                |
| Image / GIF     | Static or animated image     | ❌                    | ❌                |
| Lottie          | Animation file               | ❌                    | ❌                |
| Icon            | Decorative element           | ✅                    | ❌                |
| Video           | Embedded media               | ❌                    | ❌                |

***

#### Best Practices

* **Start simple:** use pre-built containers and headers to create clean layouts.
* **Use variables** inside Text or Button components for dynamic pricing.
* **Link product actions** early (Select Product, Make Purchase) to test your screen logic.
* **Preview frequently**: test responsiveness on iOS, Android, and tablet devices.

### Prebuilt Components

Prebuilt components are ready-to-use component templates designed to accelerate paywall creation. Instead of assembling individual elements, you can drop in a complete, styled product block and customize it to match your brand.

***

Each template comes with:

* **Pre-configured structure** with placeholder content
* **Default and selected states** with automatic styling
* **Professional design** following Qonversion best practices
* **Full customization** — every property can be modified

***

#### How to Add a Prebuilt Component

1. Open the **Left Sidebar** in the Builder.
2. Navigate to **Components** section.
3. Select a category (e.g., **Product Blocks**).
4. Browse the visual previews to find your preferred layout.
5. **Click** on a template to add it to your canvas.

<img alt="" />

<Info>
  Prebuilt Components are ideal for quickly prototyping screens or getting started with proven layouts. You can always customize every aspect after adding them to your canvas.
</Info>

#### Product Selection States

Product Block templates include automatic state-based styling:

| State              | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| **Default**        | Normal appearance when the product is not selected            |
| **Select Product** | Highlighted appearance when the user taps/selects the product |

<Frame>
  <img />
</Frame>

State changes are handled automatically when:

* User clicks/taps a product in the live paywall
* You preview the screen in the Builder

**Visual indicators for selected state typically include:**

* Border color change (purple accent)
* Text color emphasis
* Radio/checkbox fill
* Background tint adjustment

You can customize both states in the **Right Panel → States** section when a product container is selected.

***

#### Customization

After adding a prebuilt component, you have full control over every element:

#### Styling

* Colors (background, text, borders)
* Typography (font family, size, weight)
* Spacing (padding, margin, gap)
* Border radius and shadows

#### Content

* Product titles and descriptions
* Price display format
* Badge text and positioning
* Feature list items and icons

#### Behavior

* Linked products (connect to your actual store products)
* Default selected product
* Action on tap (Select Product, Make Purchase)

<Info>
  Remember to link each product container to your actual Qonversion products before publishing. Templates use placeholder product IDs that need to be updated.
</Info>

***

#### Best Practices

* **Start with a template** that matches your goals, then customize
* **Link products early** — connect to real products before extensive styling
* **Test both states** — preview how default and selected states look together
* **Use badges strategically** — highlight your recommended plan with discount or "Best Value" badges
* **Keep feature lists scannable** — 3–5 features per plan is optimal for mobile
* **Preview on multiple devices** — use the device selector to check iOS, Android, and tablet layouts

#### List of prebuilt components

1. [Product Blocks](product-blocks) - templates for subscription and purchase selection screens.
2. [Social Proof](social-proof) - customer reviews and testimonials to build trust.
3. [Carousels](carousels) - swipeable content layouts for onboarding, galleries, and navigation.
4. [CTA Buttons](cta-buttons) - ready-to-use call-to-action buttons with various styles.
5. [Feature List](feature-list) - feature lists, benefit overviews, and plan comparisons.
6. [Awards](awards) - App Store award badges and recognition displays.

***

[Creating Screens](getting-started)

[Product Blocks](product-blocks)


# Conditional Logic
Source: https://documentation.qonversion.io/docs/conditional-logic

Dynamically change component styles based on device, user properties, product context, and custom variables

Conditional logic allows you to dynamically change the appearance of any component on your paywall or onboarding screen based on runtime context — device info, selected product, user properties, or custom screen variables.

For example, you can highlight a specific product's price in bold when the user selects it, hide an element on Android, or change the background color for dark mode users.

<Warning>
  Make sure your Qonversion SDK is updated to the latest version that supports conditional logic.
  See the [SDK Requirements](#sdk-requirements) section below.
</Warning>

***

## How It Works

Each component on your screen has **style blocks** (Typography, Size, Spacing, Background, etc.). You can attach **conditional rules** to any style block. Each rule contains:

1. **Conditions** — when should this rule apply (e.g., "Platform equals iOS AND Theme equals dark")
2. **Style overrides** — what properties to change when the conditions are met (e.g., set font-size to 24px and color to white)

At runtime, the Qonversion SDK provides the context (device info, user data, product details), and the conditional logic evaluator checks each rule top-to-bottom. The **first matching rule wins** — its overrides are applied, and subsequent rules are skipped.

If no rule matches, the component keeps its default styles.

***

## Step-by-Step Example: Changing Typography for iOS Dark Mode

Let's walk through a real example. We'll change the title text style when the user is on iOS in dark mode — applying a different font, size, weight, and color to ensure the text looks great on dark backgrounds.

### 1. Select the component

Click on the text component you want to add conditional logic to. In this example, we select a title text on the paywall screen.

### 2. Open the Conditional Rules modal

In the right sidebar, find the **Typography** style block. Hover over the block header — a lightning bolt icon will appear. Click it to open the Conditional Rules modal.

### 3. Add a new rule

Click **Add Rule** at the bottom of the modal. A new empty rule appears with a condition group and a style overrides section.

### 4. Set the conditions

We need two conditions combined with AND logic:

**First condition:**

* **Variable**: select `Platform` from the Device category
* **Operator**: select `equals`
* **Value**: select `iOS`

**Second condition:**

* **Variable**: select `Theme` from the Device category
* **Operator**: select `equals`
* **Value**: select `dark`

This means: "Apply this rule when the user is on iOS AND using dark mode."

### 5. Set the style overrides

In the **Overrides** section below the conditions, configure the typography changes:

| Property    | Value                       |
| ----------- | --------------------------- |
| Font family | `System UI`                 |
| Font size   | `22` px                     |
| Font weight | `Semi Bold (600)`           |
| Color       | `#f3e5e5` (light warm tone) |
| Line height | `20` px                     |

These values will override the component's default typography when both conditions are met.

<Frame>
  <img alt="Conditional Rules modal with typography overrides" />
</Frame>

### 6. Save and preview

Click **Apply** to save the rules. The lightning bolt on the Typography block now shows a badge with the rule count.

To test it, open the **Preview Conditions Panel** (the test tube icon in the header). You can manually change the `Platform` and `Theme` variables to see how the component reacts in real time.

***

## Conditions In Detail

### Condition Groups: AND / OR

Conditions within a rule are organized in **groups**. Each group has a logical operator:

* **AND** — all conditions in the group must be true
* **OR** — at least one condition must be true

Click the `and`/`or` label between conditions to toggle the group operator.

Groups can be **nested up to 2 levels deep**, allowing complex expressions like:

```
(Platform equals iOS AND OS Version greater_or_equal 16.0)
OR
(Platform equals Android AND OS Version greater_or_equal 13.0)
```

### Available Variables

#### Device

| Variable    | Type    | Example values   |
| ----------- | ------- | ---------------- |
| Platform    | String  | `iOS`, `Android` |
| OS Version  | Version | `16.0`, `14.5.1` |
| Language    | String  | `en`, `fr`, `de` |
| Locale      | String  | `en_US`, `fr_FR` |
| Theme       | String  | `light`, `dark`  |
| App Version | Version | `1.0.0`, `2.3.1` |
| Country     | String  | `US`, `GB`, `DE` |

#### Products

| Variable               | Type    | Description                                      |
| ---------------------- | ------- | ------------------------------------------------ |
| Selected Product       | String  | The product ID the user currently has selected   |
| Has Any Intro          | Boolean | Whether any product has an introductory offer    |
| Per-product Has Intro  | Boolean | Whether a specific product has an intro offer    |
| Per-product Intro Type | String  | `free_trial`, `pay_as_you_go`, or `pay_up_front` |

Product variables are generated dynamically based on the products configured for your screen.

#### User

| Variable            | Type    | Description                                          |
| ------------------- | ------- | ---------------------------------------------------- |
| Entitlements        | Array   | List of user's active entitlements                   |
| Has Any Entitlement | Boolean | Whether the user has at least one active entitlement |
| Is First Launch     | Boolean | Whether this is the user's first app launch          |
| Days Since Install  | Number  | Number of days since the app was installed           |

#### User Properties

User properties set via the Qonversion SDK (both [defined and custom](user-properties)) are automatically available in the conditional logic context. They appear under the `user.properties` namespace.

For example, if you set a custom user property `plan` with value `premium`, you can create a condition:

* **Variable**: `user.properties.plan`
* **Operator**: `equals`
* **Value**: `premium`

This allows you to personalize screens based on any user attribute you track — subscription tier, onboarding status, A/B test group, or any other custom property.

<Info>
  User properties are loaded in parallel with other screen data, so they do not increase screen display time.
</Info>

#### Custom Screen Variables

Custom screen variables are values you inject from your app code at runtime via the `CustomVariablesDelegate`. They are unique per screen (identified by `contextKey`) and are available for conditions under the custom variables namespace.

For example, if your delegate returns `{"source": "settings"}`, you can create a condition:

* **Variable**: `source` (from Custom Variables category)
* **Operator**: `equals`
* **Value**: `settings`

See [Setting Up Custom Variables](#setting-up-custom-variables) below for implementation details.

### Available Operators

| Operator         | Works with      | Description                                            |
| ---------------- | --------------- | ------------------------------------------------------ |
| equals           | All types       | Exact match (case-insensitive for strings)             |
| not equals       | All types       | Inverse of equals                                      |
| in               | String, Version | Value is one of a comma-separated list                 |
| not in           | String, Version | Value is not in the list                               |
| contains         | Array, String   | Array includes the value, or string contains substring |
| does not contain | Array, String   | Inverse of contains                                    |
| greater than     | Number, Version | Numeric or semantic version comparison                 |
| less than        | Number, Version | Numeric or semantic version comparison                 |
| greater or equal | Number, Version | Numeric or semantic version comparison                 |
| less or equal    | Number, Version | Numeric or semantic version comparison                 |
| is empty         | Array, String   | Array has no elements, or string is empty/null         |
| is not empty     | Array, String   | Array has elements, or string is non-empty             |

<Info>
  Version comparisons (for OS Version and App Version) use semantic versioning — each segment is compared numerically. For example, `16.0` is greater than `9.3.6`.
</Info>

***

## Rule Priority

Rules are evaluated **top to bottom** within each style block. The first rule whose conditions evaluate to `true` is applied — all subsequent rules are skipped.

This means you should order your rules from **most specific to least specific**:

```
Rule 1: Platform = iOS AND Theme = dark    -> white text, large font
Rule 2: Platform = iOS                     -> dark text, large font
Rule 3: (default — no conditions match)    -> keeps default styles
```

You can drag rules to reorder them in the Conditional Rules modal.

***

## Activating and Deactivating Rules

Each style block has an **Active** toggle in the Conditional Rules modal header. When toggled off:

* All rules are preserved (not deleted)
* Rules are not evaluated at runtime
* The lightning bolt indicator remains visible but rules have no effect

This is useful for temporarily disabling conditional logic without losing your configuration.

***

## Testing with Preview Panel

You don't need to publish your screen to test conditional logic. The No-Code Builder has a built-in **Preview Conditions Panel** that lets you simulate any combination of variables and instantly see how your rules affect the screen — right inside the editor.

### How to open the panel

1. Make sure you have at least one conditional rule configured on any component
2. Switch to **Preview** mode using the toggle in the builder header
3. The **Preview Conditions Panel** automatically appears on the left side of the screen

The panel lists every variable used in your conditional rules across all components on the current screen.

### Testing variables

Each variable has an appropriate input control depending on its type:

* **Dropdowns** — for variables with predefined values (Platform, Theme, Selected Product, Intro Type, etc.). Just pick a value from the list
* **Checkboxes** — for boolean variables (Has Any Intro, Has Any Entitlement, Is First Launch, etc.). Toggle on or off
* **Text inputs** — for string and version variables (OS Version, Language, App Version, Country, etc.). Type any value to simulate
* **Number inputs** — for numeric variables (Days Since Install, etc.)

As you change values, the canvas **updates in real time** — you can see exactly which styles are applied and how the screen looks for any combination of conditions.

### Active Rules

The bottom section of the panel shows **Active Rules** — a live list of which rules are currently matching based on the current variable values. This makes it easy to verify that the right rules fire for the right conditions.

<Frame>
  <img alt="Preview Conditions Panel" />
</Frame>

<Tip>
  Try different combinations of variables to make sure your rules cover all the edge cases — for example, switching between iOS and Android while toggling dark mode, or selecting different products to verify the highlighting works correctly.
</Tip>

***

## Common Use Cases

### Highlight the selected product

**Condition**: Selected Product equals the product ID

**Typography override**: Bold font weight, accent color

**Use case**: Make the currently selected product's title or price stand out visually.

### Platform-specific layout

**Condition**: Platform equals `iOS` / `Android`

**Spacing or Size override**: Adjust padding, margins, or dimensions

**Use case**: Account for platform-specific UI conventions (e.g., larger touch targets on Android).

### Dark mode support

**Condition**: Theme equals `dark`

**Typography + Background + Border override**: Light text on dark background, adjusted border colors

**Use case**: Ensure your paywall looks great in both light and dark themes.

### Show/hide elements by entitlements

**Condition**: Has Any Entitlement equals `true`

**Appearance override**: Visibility hidden

**Use case**: Hide the purchase button for users who already have an active subscription.

### Free trial badge

**Condition**: Product Has Intro equals `true` AND Intro Type equals `free_trial`

**Appearance + Typography override**: Show a badge, change text color

**Use case**: Visually indicate which products offer a free trial.

### First-time user experience

**Condition**: Is First Launch equals `true`

**Any style override**: Different layout, larger text, highlighted CTA

**Use case**: Show a more prominent onboarding experience for first-time users.

### Personalization with custom variables

**Condition**: Custom variable `plan` equals `free`

**Typography + Appearance override**: Show upgrade messaging, accent CTA color

**Use case**: Display a prominent upgrade prompt for free-tier users while hiding it for premium subscribers. Variables are injected via `CustomVariablesDelegate`.

### Context-aware styling with user properties

**Condition**: `user.properties.loyalty_tier` equals `gold`

**Background + Typography override**: Gold accent color, exclusive badge visibility

**Use case**: Show VIP styling and exclusive offers to high-value users based on properties already tracked via the Qonversion SDK.

***

## Setting Up Custom Variables

<Warning>
  Custom Variables (and the `user.properties.*` namespace described above) are delivered to the screen context starting from the SDK versions listed in the [SDK Requirements](#sdk-requirements) table below. On earlier SDKs the rules are still embedded in the published HTML, but the corresponding values arrive empty and rules referencing them will not match.
</Warning>

Custom screen variables let you pass dynamic data from your app into the No-Code screen context at runtime. This is useful for conditions that depend on app-specific state — such as the screen the user came from, their subscription tier, or feature flags.

You provide variables by implementing a delegate that the SDK calls each time a screen is ready to display. The delegate receives a `contextKey` identifying the screen and returns a dictionary of string key-value pairs. Different screens can receive different variables.

### Implementation

<CodeGroup>
  ```swift Swift theme={null}
  class MyVariablesDelegate: NoCodesCustomVariablesDelegate {
      func customVariables(for contextKey: String) -> [String: String] {
          // Return variables specific to this screen
          return [
              "username": currentUser.name,
              "plan": currentUser.plan,
              "source": "settings"
          ]
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  class MyVariablesDelegate : CustomVariablesDelegate {
      override fun getCustomVariables(contextKey: String): Map<String, String> {
          // Return variables specific to this screen
          return mapOf(
              "username" to currentUser.name,
              "plan" to currentUser.plan,
              "source" to "settings"
          )
      }
  }
  ```

  ```java Java theme={null}
  public class MyVariablesDelegate implements CustomVariablesDelegate {
      @Override
      public Map<String, String> getCustomVariables(String contextKey) {
          // Return variables specific to this screen
          Map<String, String> variables = new HashMap<>();
          variables.put("username", currentUser.getName());
          variables.put("plan", currentUser.getPlan());
          variables.put("source", "settings");
          return variables;
      }
  }
  ```
</CodeGroup>

### Setting the delegate

You can set the delegate during initialization or at runtime:

<CodeGroup>
  ```swift Swift theme={null}
  // During initialization
  let config = NoCodesConfiguration(
      projectKey: "projectKey",
      customVariablesDelegate: myDelegate
  )
  NoCodes.initialize(with: config)

  // Or at runtime
  NoCodes.shared.set(customVariablesDelegate: myDelegate)
  ```

  ```kotlin Kotlin theme={null}
  // During initialization
  val config = NoCodesConfig.Builder(this, "projectKey")
      .setCustomVariablesDelegate(myDelegate)
      .build()
  NoCodes.initialize(config)

  // Or at runtime
  NoCodes.shared.setCustomVariablesDelegate(myDelegate)
  ```

  ```java Java theme={null}
  // During initialization
  NoCodesConfig config = new NoCodesConfig.Builder(this, "projectKey")
      .setCustomVariablesDelegate(myDelegate)
      .build();
  NoCodes.initialize(config);

  // Or at runtime
  NoCodes.getSharedInstance().setCustomVariablesDelegate(myDelegate);
  ```
</CodeGroup>

<Info>
  The delegate is called every time a screen is about to be shown, including nested screens during navigation within a NoCodes flow. Use the `contextKey` parameter to return different variables for different screens.
</Info>

### How it works

When the screen is ready to display, the SDK:

1. Calls your delegate with the screen's `contextKey`
2. Injects each returned key-value pair into the WebView JavaScript context via `window.noCodesSetVariable(name, value)`
3. The conditional logic evaluator uses these variables when checking rules

### Use cases for custom variables

| Variable       | Example value            | Use case                                                    |
| -------------- | ------------------------ | ----------------------------------------------------------- |
| `source`       | `onboarding`, `settings` | Show different styles depending on where the user came from |
| `plan`         | `free`, `premium`        | Highlight upgrade CTA for free users, hide it for premium   |
| `username`     | `John`                   | Personalize greeting text via conditional visibility        |
| `ab_group`     | `control`, `variant_a`   | Apply different layouts per experiment group                |
| `loyalty_tier` | `gold`, `silver`         | Customize offers based on loyalty status                    |

***

## SDK Requirements

Conditional logic requires the following minimum SDK versions:

| Platform                 | Conditional Logic | Custom Variables & User Properties |
| ------------------------ | ----------------- | ---------------------------------- |
| iOS                      | **6.9.0**         | **6.11.0**                         |
| Android (Qonversion SDK) | —                 | **9.4.0**                          |
| Android No-Codes SDK     | **1.7.0**         | **1.9.0**                          |
| Flutter                  | **11.4.0**        | —                                  |
| React Native             | **10.4.0**        | —                                  |
| Unity                    | **9.3.0**         | —                                  |
| Cordova                  | **7.3.0**         | —                                  |
| Capacitor                | **1.3.0**         | —                                  |

The SDK provides runtime context to the paywall via the `setContext` event. If the SDK version is too old, conditional logic rules will still be present in the published HTML but the context will be empty — meaning no rules will match and default styles will be shown.

<Info>
  Custom Variables and User Properties in the NoCodes context are currently available on iOS and Android native SDKs. Cross-platform SDK support will be added in future releases.
</Info>

***

## Limitations

* Conditional logic is available for **Mobile Paywall** and **Mobile Onboarding** screen types only
* Condition groups can be nested up to **2 levels deep**
* Each group supports up to **10 conditions**
* A soft warning appears when a style block has **20+ rules** (no hard limit)
* Rules are evaluated client-side in the published HTML — complex rule sets may have a minor performance impact
* Custom variables from the delegate are string-only (`[String: String]`) — use string comparison operators in conditions
* Custom variables are injected per screen show — they are not persisted across sessions
* User properties must be set via the Qonversion SDK before the screen is shown to be available in conditions


# Cordova
Source: https://documentation.qonversion.io/docs/cordova

Install Qonversion Cordova Plugin to validate user receipts, and get in-app subscription analytics and third-party integrations.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/cordova-plugin?label=Latest%20Release)](https://github.com/qonversion/cordova-plugin/releases)

## Install via Cordova

Qonversion Plugin package is available on [npm](https://www.npmjs.com/package/@qonversion/cordova-plugin). Add it to your project with:

<CodeGroup>
  ```bash theme={null}
  cordova plugin add @qonversion/cordova-plugin
  ```
</CodeGroup>

This downloads the package from npm and wires up the native iOS and Android modules in one step.

## Kids Mode for Qonversion Cordova Plugin

In case you are building an App for Kids, [follow this guide](kids-mode-sdk) to learn about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# Cordova 4.+ migration guide
Source: https://documentation.qonversion.io/docs/cordova-4-migration-guide

Historical migration guide for upgrading the Qonversion Cordova SDK to major version 4.+: updated initialization, renamed methods, and revised purchase and entitlement APIs.

## Upgrading version

Increase the dependency version in your package.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json theme={null}
  "cordova-plugin-qonversion": "^4.0.0"
  ```
</CodeGroup>

## Renamings

In this major version, we have renamed several entities and public methods to make our namings more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade    | After upgrade           |
| ----------------- | ----------------------- |
| `UserProperty`    | `UserPropertyKey`       |
| `setUserProperty` | `setCustomUserProperty` |
| `setProperty`     | `setUserProperty`       |

## User properties changes

As mentioned above, we have renamed the`UserProperty` enum to `UserPropertyKey`. It was made to release the name `UserProperty` for a class, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```typescript Cordova theme={null}
  try {
    const userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach(userProperty => {
      console.log('User property - key:' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

`UserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                 | Description                                                                                              |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `getProperty`        | `key` - string            | Searches for a property with the given property `key` in all properties list                             |
| `getDefinedProperty` | `key` - `UserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `UserPropertyKey` enum with a `CUSTOM` key to represent all the custom properties.

***

[Unity 6.+ migration guide](unity-6-migration-guide)

[Web 1.+ migration guide](web-1-migration-guide)


# Cordova SDK 4.x to 5.x migration guide
Source: https://documentation.qonversion.io/docs/cordova-5-migration-guide

We've upgraded the Google Play Billing Library dependency on Android to version 6 in this release, which has led to major changes in the product and subscription management parts of our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *package.json* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json theme={null}
  "cordova-plugin-qonversion": "^5.0.0"
  ```
</CodeGroup>

## Product updates

### Qonversion and Google Play product link changes

Google Play has recently upgraded the structure of their subscription products. We've written about it [in our blog](https://qonversion.io/blog/google-play-billing-library-5-0/). In short, they combined the same subscriptions with different durations into a single subscription with different base plans. In addition, they announced different kinds of offers to base plans, including free trials or introductory prices. In this release, we begin to support those changes.

Previously Qonversion **subscription** products required a Google Play subscription identifier. Now you can also set a specific **base plan** for the subscription. Different base plans of the same subscription can be linked to different Qonversion products. Let's have a look at an example.

Let's say you sell monthly and annual subscriptions in your app, both on Android and iOS. With the previous Qonversion SDK versions, you would specify two Qonversion products (`premium_monthly` and `premium_annual`), two App Store products (`premium_monthly_ios` and `premium_annual_ios`), and two Google Play products (`premium_monthly_android` and `premium_annual_android`). Then you would link those store products to Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_monthly_android`,

`premium_annual` - `premium_annual_ios` and `premium_annual_android`.

With the new Google Play Subscriptions structure, you can create only one subscription for Android - `premium_android` and two base plans for it (`monthly` and `annual`). With this done, you can now use a single subscription for both Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_android` with `monthly` base plan,

`premium_annual` - `premium_annual_ios` and `premium_android` with `annual` base plan.

### Store details for the `QProduct` class

Speaking of the SDK side - the first big part of the changes is the addition of the new `basePlanId` field to `Product` which can be set to the product via Qonversion Dashboard.

We have deprecated the `Product.skuDetails` field, because `SkuDetails` contain information only for backward compatible base plans and are now deprecated in the Google Play Billing Library. Instead, we have added the new `storeDetails` field of type `ProductStoreDetails`, which contains all the store information for the Google Play Product. You can find the specifications of that class [on this page](google-play-product-details).

If `basePlanId` is not specified for a product, it means one of the following:

* it is a one-time (in-app) product that can not have any base plans,
* it is a product that was not updated in the Qonversion dashboard after this version was released,
* it is an iOS-only product.

In the case of the in-app product, both `skuDetails` and `storeDetails` fields will contain information about that in-app. But in the second case, when there is a subscription product without a specified base plan, the `skuDetails` field will contain information about the **backward compatible** base plan, while the `storeDetails` field will only contain common subscription information without base-plan-specific data. It means that you should start using `storeDetails` field for base-plan-specific data (like price, duration, and so on) for Android subscription products only if you've specified their base plan IDs in Qonversion product settings.

### The other `Product` fields changes

Along with the above changes, we have changed the `type` field and removed the `duration` and `trialDuration` fields from the product class. The `type` and `duration` were previously being set via the dashboard, and the `trialDuration` was calculated from the store details and was represented as an enumeration with several common durations. Now, the product `type` is calculated from the store details both for Android and iOS. We've also added the `INTRO` value to `ProductType` to separate `trial` and `intro` products (Android only for now). An `UNKNOWN` value was also added for the cases where we are unable to determine the product type. The `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod`. Both properties are of type `SubscriptionPeriod` and the values are also calculated from the store details for both platforms.

The last thing to note is that we've also changed the `prettyPrice` and `prettyIntrodactoryPrice` fields calculation for Android. Earlier they were calculated from `skuDetails`, while now we first try to use `storeDetails` if possible and only then fall back to `skuDetails`.

### `Product` updates summary

Below is the shortened summary of the `Product` changes:

* new `basePlanId` field, specifying concrete subscription base plan for Google Play subscriptions, added,
* `skuDetails` field deprecated,
* new `storeDetails` field, containing information about Google Play product, added;
* the `type` field is now calculated based on store details both for Android and iOS, instead of the value set via the Qonversion dashboard. The `INTRO` and `UNKNOWN` values were added to `ProductType` to separate cases of trial and intro products (Android only for now) and also the case when we are unable to determine the product type;
* the `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod` fields of type `SubscriptionPeriod` with the values calculated from the store details both for Android and iOS;
* the `prettyPrice` and `prettyIntroductoryPrice` fields on Android now prefers `storeDetails` to get the price from, and only then - `skuDetails`.

## Purchase flow updates

In this release, we have changed the `purchase` and `updatePurchase` methods signatures. Previously there were several methods for different sets of arguments. Now we've arranged all those properties into classes - `PurchaseModel` and `PurchaseUpdateModel`, that should be instantiated and provided to the single `purchase` or `updatePurchase` method.

You can create instances of those classes either manually or by using the utility functions `toPurchaseModel` and `toPurchaseUpdateModel` added to the `Product` class.

Below is an example of how the `purchase` flow has changed:

<CodeGroup>
  ```typescript Cordova theme={null}
  // Old
  const entitlements = await Qonversion.getSharedInstance().purchaseProduct(product);

  // New
  const purchaseModel = product.toPurchaseModel();
  const entitlements = await Qonversion.getSharedInstance().purchase(purchaseModel);
  ```
</CodeGroup>

And an `updatePurchase` flow example:

<CodeGroup>
  ```typescript Cordova theme={null}
  // Old
  const entitlement = await Qonversion.getSharedInstance().updatePurchaseWithProduct(product, 'oldProductId');

  // New
  const purchaseUpdateModel = product.toPurchaseUpdateModel('oldProductId');
  const entitlement = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

If you were using only product identifiers, you can create purchase models manually as follows:

<CodeGroup>
  ```typescript Cordova theme={null}
  // Old
  const entitlements = await Qonversion.getSharedInstance().purchase('productId');

  // New
  const purchaseModel = new PurchaseModel('productId');
  const entitlement = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

<CodeGroup>
  ```typescript Cordova theme={null}
  // Old
  const entitlement = await Qonversion.getSharedInstance().updatePurchase('newProductId', 'oldProductId');

  // New
  const purchaseUpdateModel = new PurchaseUpdateModel('newProductId', 'oldProductId');
  const entitlement = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

If necessary, you can provide a specific offer for subscription purchase.

<CodeGroup>
  ```typescript Cordova theme={null}
  // Specifying offer via the `toPurchaseModel` method:
  const productOfferDetails = ...; // Choose an offer from `storeDetails`
  const purchaseModel = product.toPurchaseModelWithOffer(productOfferDetails);

  // Specifying offer ID via the `toPurchaseModel` method:
  const purchaseModel = product.toPurchaseModel('offer_id');

  // Specifying offer ID via the constructor:
  const purchaseModel = new PurchaseModel('productId', 'offer_id');
  const purchaseUpdateModel = new PurchaseUpdateModel('newProductId', 'oldProductId', 'offer_id');

  // Specifying offer ID after the purchase model creation:
  purchaseModel.offerId = 'offer_id';
  ```
</CodeGroup>

If provided, we will try to find and purchase the offer with the specified ID for the requested Qonversion product. If there is no offer with the specified ID, an error will be returned. If no offer ID is provided for the subscription purchase of Qonversion product with a specified base plan ID, then we will choose the most profitable offer for the client from all the available offers. We calculate the cheapest price for the client by comparing all the trial or intro phases and the base plan. For iOS, old Qonversion products (where the base plan ID is not specified), or in-app products, the offer ID is ignored.

You can also remove any intro/trial offer from the purchase (use only a bare base plan). For that purpose, you should call `removeOffer` method of purchase model:

<CodeGroup>
  ```typescript Cordova theme={null}
  purchaseModel.removeOffer();
  ```
</CodeGroup>

## The other changes

* The `checkTrialIntroEligibility` method improved and now detects the eligibility based on store details on Android;
* The `ProductDuration` and `TrialDuration` classes were removed;
* The `ProductType` enum values were changed to meet guidelines;
* The `ProrationMode` enum was removed and replaced with `PurchaseUpdatePolicy` ([read more](making-purchases)).

***

[Unity SDK 6.x to 7.x migration guide](unity-7-migration-guide)

[\[Aug 2023\] Migration Guide](qonversion-sdk-major-version)


# Cordova SDK 5.x to 6.x migration guide
Source: https://documentation.qonversion.io/docs/cordova-6-migration-guide

We've upgraded the Google Play Billing Library dependency for Android to version 7 in this release, leading to several changes in our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *package.json* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json theme={null}
  "cordova-plugin-qonversion": "^6.0.0"
  ```
</CodeGroup>

## Android deployment upgrades

With the new Google Play Billing Library 7 we've increased our `minSdkVersion` to 21 and `targetSdkVersion` to 34 for Android.

If you were using lower `minSdkVersion` you should upgrade it to 21 to use the latest version of our SDK and Google Play Billing Library. If you have already targeted the 21+ version, you should do nothing.

## Installment plans support

In the latest library version, Google introduces installment plans, when a customer commits to pay for several subsequent subscription periods. In our release, we've added a new field `installmentPlanDetails` to `ProductOfferDetails` with the details of the installment plan if they exist. It contains the following information:

| Field                               | Type | Description                                                               |
| ----------------------------------- | ---- | ------------------------------------------------------------------------- |
| `commitmentPaymentsCount`           | Int  | Committed payments count after a user signs up for this subscription plan |
| `subsequentCommitmentPaymentsCount` | Int  | Subsequent committed payments count after this subscription plan renews   |

We've also added an `isInstallment` flag to `ProductStoreDetails` to check if the current product has an installment plan or not.

Below is an example of those fields usage:

<CodeGroup>
  ```typescript Cordova theme={null}
  const products = await Qonversion.getSharedInstance().products();
  const installmentProduct = products['installmentProductId'];
  const storeDetails = installmentProduct?.storeDetails;
  if (storeDetails?.isInstallment) {
    const installmentDetails = storeDetails?.basePlanSubscriptionOfferDetails?.installmentPlanDetails;
    // Use the installment plan information
  }
  ```
</CodeGroup>

## Fallback files

We're happy to introduce the fallback files support in this release to make our system reliability even higher. Fallback files allow your app to work as expected in rare cases of network connection or Qonversion API issues for new users without a cache available. This allows purchases and entitlements to be processed for new users even if the Qonversion API faces issues. This also makes it possible to receive remote configs for cases when the network connection is unavailable.

Fallback files are available both on iOS and Android.

Read more about the fallback files in [the documentation](system-reliability#fallback-files).

## Error codes

In this release, we have added the `QonversionErrorCode` enum with the list of defined Qonversion error codes. Now you can compare any error code with the defined one to check any specific case as follows:

<CodeGroup>
  ```typescript Cordova theme={null}
  try {
    await Qonversion.getSharedInstance().purchase(...);
  } catch (e) {
    if (e.code === QonversionErrorCode.STORE_PRODUCT_NOT_AVAILABLE) {
      // The requested product is unavailable for purchase. 
    }
  }
  ```
</CodeGroup>

We've also changed the type of `QonversionError.code` field from `string` to `QonversionErrorCode`.

## The other changes

* Pending purchases support was added for prepaid subscriptions on Android.

***

[Unity SDK 7.x to 8.x migration guide](unity-8-migration-guide)

[\[Jan 2024\] Migration guide. Google Play Billing Library 6.](qonversion-sdk-major-version-copy)


# Create Products
Source: https://documentation.qonversion.io/docs/create-products

Qonversion Product is a cross-platform entity representing products from Apple, Google, Stripe, or Paddle. This mapping helps you provide users with access to premium content after making a purchase.

## Create a Product

1. Navigate to the [Entitlements & Products configuration section](https://dash.qonversion.io/entitlements/products). Tap the Create button and select Product.

<img alt="" />

2. Fill in the product details.

<img alt="" />

* **Qonversion Product ID** – create your unique product identifier in Qonversion that corresponds to a unique product on the Apple App Store and Google Play Store. The SDK will use it to make purchases.

* **AppStore Product ID** – product identifier on Apple App Store. You can read [here](https://qonversion.io/blog/configure-iap-app-store-connect/) how to create a subscription.

* **Google Play Product ID** – product identifier on Google Play Console. You can read [here](android-in-app-products) how to create a subscription.

* **Google Play Base Plan ID** (shown as **Google Play Purchase Option ID** for one-time products) - for a Google Play subscription, the identifier of the base plan (required when your app uses the Qonversion Android SDK 9+ / Google Play Billing Library 8 — see the [migration guide](july-2025-migration-guide-google-play-billing-library-8)); for a one-time (in-app) product, the identifier of the [purchase option](https://developer.android.com/google/play/billing/one-time-products), which you can leave empty to use the product's default purchase option. Different base plans or purchase options of the same store product can be linked to different Qonversion products.

* **Stripe Product ID** – product identifier in Stripe (starts with `prod_`). See the [Stripe Integration](stripe-integration) guide.

* **Paddle Product ID** – product identifier in Paddle (starts with `pro_`). See the [Paddle Integration](paddle-integration) guide.

* **Associated Entitlements** - choose the entitlements that should be granted once this product is purchased.

<Info>
  ### Change the promoted product in your app without releasing a new app version

  You can change the App Store products associated with the Qonversion product by changing the App Store Product IDs.
</Info>

***

[Create Entitlements](entitlements)

[Displaying Products](displaying-products)


# CTA Buttons
Source: https://documentation.qonversion.io/docs/cta-buttons

Call-to-action button templates designed to drive conversions. Each template includes a pre-styled button with optional supporting text, icons, and visual effects.

All CTA Button templates support:

* **Make Purchase action** — ready to connect to your products
* **Full customization** — colors, fonts, shadows, gradients
* **Responsive design** — adapts to different screen widths

***

### Simple Black

A clean, minimalist black button with white text. Perfect for straightforward calls-to-action.

<img alt="" />

**Features:**

* Solid black background
* Centered text label
* Rounded corners
* Hover/press state styling

**Use for:**

* Primary purchase buttons
* Simple "Continue" or "Subscribe" actions
* Minimalist paywall designs

***

### Extra Text

A button with additional descriptive text below and stroke effect styling.

<img alt="" />

**Features:**

* Main action text
* Supporting description text below
* Stroke/outline effect
* Two-line layout

**Use for:**

* Buttons with price or trial information
* Actions that need additional context
* Promotional CTAs with details

***

### Icon Gradient

A vibrant button with an icon and gradient background for maximum visual impact.

<img alt="" />

**Features:**

* Customizable icon (left-aligned)
* Gradient background
* Bold text styling
* Eye-catching visual treatment

**Use for:**

* Premium upgrade buttons
* Feature unlock actions
* High-conversion CTAs

***

### Two Line Shadow

A two-line button with shadow effect and supporting text for detailed calls-to-action.

<img alt="" />

**Features:**

* Primary action text (large)
* Secondary description text (smaller)
* Drop shadow effect
* Professional card-like appearance

**Use for:**

* Subscription buttons with pricing
* Trial start actions with duration info
* Premium CTAs with value proposition

***

## Customization

After adding a CTA Button template, you can customize:

**Visual styling:**

* Background color or gradient
* Text colors and typography
* Border radius and shadows
* Icon selection and color

**Content:**

* Main button text
* Supporting description text
* Icon choice

**Behavior:**

* Action type (Make Purchase, Open URL, Go to Page)
* Linked product for purchases

***

## Best Practices

* **Use action-oriented text** — "Start Free Trial" is better than "Submit"
* **Include value proposition** — add pricing or benefit in secondary text
* **Make it prominent** — CTA should be the most visible element
* **Test different styles** — gradient buttons often outperform flat ones
* **Position strategically** — place above the fold and after key benefits
* **Use consistent styling** — match your app's brand colors

***

***

[Carousels](carousels)

[Feature List](feature-list)


# Custom Actions
Source: https://documentation.qonversion.io/docs/custom-actions

Define your own actions in No-Code screens and handle them in your app code.

## Overview

Custom Actions let you add your own handling for taps in a No-Code screen. Unlike built-in actions (purchase, restore, close, etc.), a Custom Action is not executed by the SDK — it is handed over to your app through the No-Codes delegate, and your code decides what happens.

Each Custom Action is configured with a **value** — an arbitrary string that identifies the action, so your app code can tell which one was triggered.

Use Custom Actions to run app-specific logic right from a No-Code screen, for example:

* Open a native screen of your app
* Start a support chat
* Log a custom analytics event
* Toggle an app feature

***

## Configuration

To configure a Custom Action in the No-Code Builder:

1. Select a component
2. In the **Action** section of the right sidebar, choose **Custom action**
3. Enter the **Value** — the string your app code will use to identify this action

When **Platform-Specific Actions** is enabled, you can configure different values (or entirely different actions) for iOS and Android independently.

<Info>
  Custom Actions are available for mobile screens only. For Web Funnel screens the action is not offered in the builder — there is no SDK delegate on the web to receive it.
</Info>

***

## Handling in Your App

When a Custom Action is triggered, the SDK fires the standard action lifecycle callbacks (<a href="/docs/displaying-no-codes#action-execution-start-event">started</a> → <a href="/docs/displaying-no-codes#action-execution-finish-event">finished</a>) and, in between, calls a dedicated delegate method. The configured value tells your code which action to run:

<CodeGroup>
  ```swift Swift theme={null}
  extension MyClass: NoCodesDelegate {
    func noCodesReceivedCustomAction(value: String) {
      switch value {
      case "open_settings":
        // navigate to your native settings screen
      case "start_chat":
        // open your support chat
      default:
        break
      }
    }
  }
  ```

  ```kotlin Kotlin theme={null}
  class MyActivity : AppCompatActivity(), NoCodesDelegate {
    override fun onCustomAction(value: String) {
      when (value) {
        "open_settings" -> { /* navigate to your native settings screen */ }
        "start_chat" -> { /* open your support chat */ }
      }
    }
  }
  ```

  ```java Java theme={null}
  public class MyActivity extends AppCompatActivity implements NoCodesDelegate {
    @Override
    public void onCustomAction(@NonNull String value) {
      switch (value) {
        case "open_settings":
          // navigate to your native settings screen
          break;
        case "start_chat":
          // open your support chat
          break;
      }
    }
  }
  ```
</CodeGroup>

Keep in mind:

* The SDK performs no built-in handling — the whole behavior is up to your app code.
* The screen stays open. Close it with `NoCodes.shared.close()` (iOS) / `NoCodes.shared.close()` (Android) if your custom logic requires it.
* If no value was configured for the action, an empty string is delivered.

<Info>
  On cross-platform SDKs, Custom Actions are delivered through the platform-specific listener: the optional `onCustomAction(value)` callback on React Native, Cordova, and Capacitor, the `customActionStream` on Flutter, and the optional `NoCodesCustomActionDelegate` interface on Unity. See [Custom action received event](displaying-no-codes#custom-action-received-event).
</Info>

***

## Minimum SDK Versions

Custom Actions require the following minimum SDK versions:

| Platform     | Minimum Version |
| ------------ | --------------- |
| iOS          | 6.13.0          |
| Android      | No-Codes 1.10.0 |
| React Native | 10.9.0          |
| Flutter      | 11.8.0          |
| Cordova      | 7.7.0           |
| Capacitor    | 1.6.0           |
| Unity        | 9.7.0           |

<Info>
  ### **Note**

  Older SDK versions silently ignore Custom Actions — tapping the element does nothing, and no delegate callbacks are fired.
</Info>

***

[Success and Failure Actions](success-failure-actions)

[Using No-Codes with custom purchases handling](using-no-codes-with-custom-purchases-handling)


# Custom Proxy Server
Source: https://documentation.qonversion.io/docs/custom-proxy-server-for-sdks

Qonversion SDKs support Proxy URL settings. For example, you can use this feature for the following tasks

1. Log SDK requests on your server
2. Proxy SDK requests in case there are some network restrictions

To leverage this feature, set your Proxy URL using the `setProxyURL` function. Once you implement it, all requests from our mobile SDK will be sent to your API, which should proxy that requests to our API and back.

<CodeGroup>
  ```swift Swift theme={null}
  let config = Qonversion.Configuration(projectKey: "projectKey", launchMode: select_needed_launch_mode)
  config.setProxyURL("your_server_proxy_URL")
  Qonversion.initWithConfig(config)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:select_needed_launch_mode];
  [config setProxyURL:@"your_server_proxy_URL"];
  [Qonversion initWithConfig:configuration];
  ```

  ```java Java theme={null}
  final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
          this,
          "projectKey",
          select_needed_launch_mode
  )
          .setProxyURL("your_server_proxy_URL")
          .build();
  Qonversion.initialize(qonversionConfig);
  ```

  ```kotlin Kotlin theme={null}
  val qonversionConfig = QonversionConfig.Builder(
      this,
      "projectKey",
      select_needed_launch_mode
  )
      .setProxyURL("your_server_proxy_URL")
      .build()
  Qonversion.initialize(qonversionConfig)
  ```

  ```dart Flutter theme={null}
  final config = new QonversionConfigBuilder(
    'projectKey',
    select_needed_launch_mode
  ).setProxyURL('your_server_proxy_URL')
   .build();
  Qonversion.initialize(config);
  ```

  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    select_needed_launch_mode
  ).setProxyURL('your_server_proxy_URL')
   .build();
  Qonversion.initialize(config);
  ```

  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
      "projectKey",
      select_needed_launch_mode
  ).SetProxyURL("your_server_proxy_URL")
   .Build();
  Qonversion.Initialize(config);
  ```

  ```typescript Cordova theme={null}
  const config = new Qonversion.ConfigBuilder(
    'projectKey',
    select_needed_launch_mode
  ).setProxyURL('your_server_proxy_URL')
   .build();
  Qonversion.initialize(config);
  ```

  ```typescript Capacitor theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    select_needed_launch_mode
  ).setProxyURL('your_server_proxy_URL')
   .build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

***

[Scheduled Reports](scheduled-reports)

[Qonversion No-Code Builder](no-codes)


# Customer Details
Source: https://documentation.qonversion.io/docs/customer-details

This tab contains a wealth of information about your customers and their interactions with your app or subscription business, such as the total amount spent, subscription events, status, and other attributes.

<Frame>
  <img />
</Frame>

<Note>
  The Qonversion ID and identity stay the same across sandbox and production, but the subscriptions, entitlement grants, customer history, devices, and revenue shown on this page are environment-scoped. Use the **Sandbox mode** icon in the top bar to switch which environment's data is loaded for the customer.
</Note>

### Subscription widget

The Subscription widget presents information about the user's last tracked subscription.

| Field Name          | Description                                                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status              | The subscription status (Trial, Trial Cancelled, Trial Billing Retry, Active, Subscription Cancelled, Subscription Billing Retry, No Subscription). |
| Started             | The date the subscription was started.                                                                                                              |
| Last Payment        | The date the last payment for this subscription was tracked.                                                                                        |
| Subscription period | The subscription period (Weekly, Monthly, Yearly, etc.).                                                                                            |
| Price               | Subscription price in USD and original currency.                                                                                                    |
| Renewal date        | The date when the subscription is expected to be renewed.                                                                                           |
| Total               | The total sum of payments made for the subscription and the number of payments.                                                                     |
| Store               | The name of the store using which the subscription was made. AppStore, Google Play, or Stripe.                                                      |

### Overview

The Overview widget helps you quickly look at your customers' main attributes.

| Field Name        | Description                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| Created At        | The date the user was recognized by Qonversion and created. In other words, the first app launch date.              |
| Sales             | The total sum of payments made by the user after deducting refunds. Consists of subscription and one-time payments. |
| Payment Count     | The total number of payments made by the user. Consists of subscription and one-time payments.                      |
| Last Payment Date | The date the last payment from the user was tracked.                                                                |

### Entitlements

The Entitlements widget displays entitlements granted to the user, both active and expired.

| Field Name         | Description                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Entitlement name   | The name of granted entitlement that previously was configured through [our dashboard](entitlements) for the [Subscription Management SDK mode](subscription-management-mode). |
| Source             | The source through which the entitlement was granted (App Store, Google Play, Stripe, Manual).                                                                                 |
| Entitlement period | The period during which the entitlement was active.                                                                                                                            |

### Customer History

The timeline with the customer's transaction events. Here you can find event names that [Qonversion tracks](integrations-overview#tracked-events)

### User Details

| Field Name             | Description                                                                                                                                                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Qonversion ID          | Unique user ID assigned by Qonversion.                                                                                                                                                                                                                                 |
| Device ID              | The [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) or [Settings Secure Android ID](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID), depending on the user's platform |
| Identity ID            | Cross-device & cross-platform user identification you can set up by following [this guide](user-identifiers#3-user-identity).                                                                                                                                          |
| Country                | User country collected by Qonversion SDKs.                                                                                                                                                                                                                             |
| OS                     | The last OS name & version tracked by Qonversion SDKs.                                                                                                                                                                                                                 |
| Model                  | Device model collected by Qonversion SDKs.                                                                                                                                                                                                                             |
| App version            | The last app version tracked.                                                                                                                                                                                                                                          |
| SDK version            | The last Qonversion SDK version tracked.                                                                                                                                                                                                                               |
| Created At             | The date the user was recognized by Qonversion and created. In other words, the first app launch date.                                                                                                                                                                 |
| First Transaction Date | The date the first user event was tracked.                                                                                                                                                                                                                             |
| First Payment Date     | The date the first event with revenue was tracked.                                                                                                                                                                                                                     |
| Last Payment Date      | The date the last event with revenue was tracked.                                                                                                                                                                                                                      |

***

[Edit Entitlements](edit-entitlements)

[Apple Ads](apple-search-ads-analytics)


# Customers
Source: https://documentation.qonversion.io/docs/customers

Analyze subscriber cohorts with metrics like active trials, subscriptions, churn rate, and payments for users acquired in a chosen date range.

The Customers dashboard provides the data for a cohort of users who made payments in the selected period. For example, if you chose the Jan 1 to Jan 30 date range, you will get the metrics for the cohort or paying users acquired during this period based on their **subscription start date** or the **one-time purchase date**.

<iframe />

## Available Metrics

<Frame>
  <img />
</Frame>

| Name               | Description                                                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Active Trials      | The number of trials active to date.                                                                                                                |
| Active Subscribers | The number of subscriptions active to date.                                                                                                         |
| Billing Retry      | The number of subscribers in the billing retry state to date.                                                                                       |
| Sales              | The total revenue before App Stores commissions from users acquired in the selected period, including renewals, one-time payments, and net refunds. |
| Canceled Trials    | The percentage of started trials canceled to date.                                                                                                  |
| Churn Subscribers  | The percentage of users that have canceled a subscription to date.                                                                                  |
| Avg. Payment Count | The total number of payments divided by the number of users that converted after a free trial, started a subscription or made a one-time purchase.  |
| Avg. Payment Value | The total revenue divided by the total number of payments.                                                                                          |

<Info>
  All metrics in this section relate to a cohort of trial or paying users acquired in the selected period based on either the subscription start date or the one-time purchase date
</Info>

<Note>
  The Customers list only includes users who have triggered at least one transaction event (trial, subscription, one-time purchase, or renewal). Newly created users with no events yet do not appear here until they fire their first event - use the customer search to look them up directly by Qonversion ID, identity, or email. See [Sandbox Testing](testing#3-how-sandbox-and-production-data-are-organized) for more on how environment scoping affects the dashboard.
</Note>

***

What’s Next

* [Edit Entitlements](edit-entitlements)
* [Customer Details](customer-details)


# Deferred Purchases
Source: https://documentation.qonversion.io/docs/deferred-purchases

Handle deferred and pending in-app purchases caused by SCA confirmation, parental controls, or other interruptions using entitlement update listeners.

## Deferred and pending purchases

Deferred or interrupted in-app purchases may happen when [SCA](https://developer.apple.com/support/psd2) confirmation is needed, in the case of parental control and some other cases. Here is what the deferred purchase flow looks like:

* a user initiates a purchase
* purchase is received in state `deferred.`
* you receive a purchase result with a pending purchase status (`isPending` / `IsPending` on every platform; verified for hybrid SDKs at `react-native-sdk/src/dto/PurchaseResult.ts:74-76`)

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().purchase(product) { (result) in
    if result.isPending {
      // Handle pending purchase
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
    if (result.isPending) {
      // Handle pending purchase
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().purchase(this, product, new QonversionPurchaseCallback() {
      @Override
      public void onResult(@NonNull QPurchaseResult result) {
          if (result.isPending()) {
              // Handle pending purchase
          }
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.purchase(this, product, object : QonversionPurchaseCallback {
      override fun onResult(result: QPurchaseResult) {
          if (result.isPending) {
              // Handle pending purchase
          }
      }
  })
  ```

  ```dart Flutter theme={null}
  final result = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isPending) {
    // Handle pending purchase
  }
  ```

  ```typescript React Native theme={null}
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isPending) {
    // Handle pending purchase
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Purchase(product, (result) =>
  {
      if (result.IsPending)
      {
          // Handle pending purchase
      }
  });
  ```

  ```typescript Cordova theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isPending) {
    // Handle pending purchase
  }
  ```

  ```typescript Capacitor theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isPending) {
    // Handle pending purchase
  }
  ```
</CodeGroup>

* if a transaction completes successfully later, Apple StoreKit or Google Billing Service returns a successful purchase
* Qonversion SDK returns a successful purchase

Make sure your app handles deferred or interrupted transactions by setting a delegate and a function that is triggered when such a transaction is made.

<Warning>
  ### Attention

  Please note, this function is called only in case of deferred purchases. The purchase flow happens as described [here](making-purchases#1-make-a-purchase) for all other cases.
</Warning>

### Provide entitlements update listener

<Warning>
  `setEntitlementsUpdateListener` is deprecated. Use `setDeferredPurchasesListener` (`QDeferredPurchasesListener` on Android, `QONDeferredPurchasesListener` on iOS) instead - it provides full transaction details (product ID, transaction ID, value), not only the resulting entitlements. The deprecated listener will continue to work for now.
</Warning>

Set the delegate to handle pending purchases and implement the corresponding function to handle new entitlements when the purchase is completed.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setEntitlementsUpdateListener(self)

  ...

  func didReceiveUpdatedEntitlements(_ entitlements: [String : Qonversion.Entitlement]) {
      // handle updated entitlements here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setEntitlementsUpdateListener:self];

  ...

  - (void)didReceiveUpdatedEntitlements:(NSDictionary<NSString *, QONEntitlement *>  * _Nonnull)entitlements {
      // handle updated entitlements here
  }
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setEntitlementsUpdateListener(entitlements -> {
      // handle updated entitlements here
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setEntitlementsUpdateListener(object : QEntitlementsUpdateListener {
      override fun onEntitlementsUpdated(entitlements: Map<String, QEntitlement>) {
          // handle updated entitlements here
      }
  })
  ```

  ```dart Flutter theme={null}
  StreamSubscription<Map<String, QEntitlement>> _updatedEntitlementsStream;
  _updatedEntitlementsStream = Qonversion.getSharedInstance().updatedEntitlementsStream.listen((entitlements) => {
     // handle updated entitlements here
  });
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setEntitlementsUpdateListener({
      onEntitlementsUpdated(entitlements) {
          // handle updated entitlements here
      },
  });
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().UpdatedEntitlementsReceived += HandleUpdatedEntitlements;

  private void HandleUpdatedEntitlements(Dictionary<string, Entitlement> entitlements)
  {
      // handle updated entitlements here
  }
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setEntitlementsUpdateListener({
      onEntitlementsUpdated(entitlements) {
          // handle updated entitlements here
      },
  });
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setEntitlementsUpdateListener({
      onEntitlementsUpdated(entitlements) {
          // handle updated entitlements here
      },
  });
  ```
</CodeGroup>

You can also provide a listener during the initialization for some platforms as follows:

<CodeGroup>
  ```java Java theme={null}
  final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
          this,
          "projectKey",
          QLaunchMode.SubscriptionManagement
  )
          .setEntitlementsUpdateListener(entitlements -> {
              // handle updated entitlements here
          })
          .build();
  Qonversion.initialize(qonversionConfig);
  ```

  ```kotlin Kotlin theme={null}
  val qonversionConfig = QonversionConfig.Builder(
      this,
      "projectKey",
      QLaunchMode.SubscriptionManagement
  )
      .setEntitlementsUpdateListener(object : QEntitlementsUpdateListener {
          override fun onEntitlementsUpdated(entitlements: Map<String, QEntitlement>) {
              // handle updated entitlements here
          }
      })
      .build()
  Qonversion.initialize(qonversionConfig)
  ```

  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEntitlementsUpdateListener({
        onEntitlementsUpdated(entitlements) {
            // handle updated entitlements here
        },
    })
    .build();
  Qonversion.initialize(config);
  ```

  ```typescript Cordova theme={null}
  const config = new Qonversion.ConfigBuilder(
    'projectKey',
    Qonversion.LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEntitlementsUpdateListener({
        onEntitlementsUpdated(entitlements) {
            // handle updated entitlements here
        },
    })
    .build();
  Qonversion.initialize(config);
  ```

  ```typescript Capacitor theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEntitlementsUpdateListener({
        onEntitlementsUpdated(entitlements) {
            // handle updated entitlements here
        },
    })
    .build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

***

[Tutorials](tutorials)

[Non-Subscription Purchases](non-subscription-purchases)


# Displaying No-Codes
Source: https://documentation.qonversion.io/docs/displaying-no-codes

First, you need to initialize the SDK. To do this, use the same project key that you use to initialize the Qonversion SDK.

<CodeGroup>
  ```swift Swift theme={null}
  // You can initialize using only project key
  let configuration = NoCodesConfiguration(projectKey: "projectKey")
  NoCodes.initialize(with: configuration)
  ```

  ```kotlin Kotlin theme={null}
  // You can initialize using only project key
  val noCodesConfig = NoCodesConfig.Builder(this, "projectKey").build()
  NoCodes.initialize(noCodesConfig)
  ```

  ```java Java theme={null}
  // You can initialize using only project key
  final NoCodesConfig noCodesConfig = new NoCodesConfig.Builder(this, "projectKey").build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```typescript React Native theme={null}
  // You can initialize using only project key
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```dart Flutter theme={null}
  // You can initialize using only project key
  final noCodesConfig = new NoCodesConfigBuilder(projectKey).build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```csharp Unity theme={null}
  // You can initialize using only project key
  var noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .Build();
  NoCodes.Initialize(noCodesConfig);
  ```

  ```typescript Cordova theme={null}
  // You can initialize using only project key
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder('projectKey')
    .build();
  Qonversion.NoCodes.initialize(noCodesConfig);
  ```

  ```typescript Capacitor theme={null}
  // You can initialize using only project key
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .build();
  NoCodes.initialize(noCodesConfig);
  ```
</CodeGroup>

Then you can set the delegates for handling events and customizing screens as follows - *(optional)*:

<CodeGroup>
  ```swift Swift theme={null}
  // The first delegate is used for main events (e.g., screen opened, button tapped).
  NoCodes.shared.set(delegate: self)
  // The second is for screen customization (if you want to override default styles).
  NoCodes.shared.set(screenCustomizationDelegate: self)

  // Delegates can be also passed via the initialization through the configuration:
  let noCodesConfig = NoCodesConfiguration(projectKey: "projectKey", delegate: self, screenCustomizationDelegate: self)
  ```

  ```kotlin Kotlin theme={null}
  // The first delegate is used for main events (e.g., screen opened, button tapped).
  NoCodes.shared.setDelegate(this)
  // The second is for screen customization (if you want to override default styles).
  NoCodes.shared.setScreenCustomizationDelegate(this)

  // Delegates can be also passed via the initialization through the configuration:
  val noCodesConfig = NoCodesConfig.Builder(this, "projectKey")
    .setDelegate(this)
    .setScreenCustomizationDelegate(this)
    .build()
  ```

  ```java Java theme={null}
  // The first delegate is used for main events (e.g., screen opened, button tapped).
  NoCodes.getSharedInstance().setDelegate(this);
  // The second is for screen customization (if you want to override default styles).
  NoCodes.getSharedInstance().setScreenCustomizationDelegate(this);

  // Delegates can be also passed via the initialization through the configuration:
  final NoCodesConfig noCodesConfig = new NoCodesConfig.Builder(this, "projectKey")
    .setDelegate(this)
    .setScreenCustomizationDelegate(this)
    .build();
  ```

  ```typescript React Native theme={null}
  // Set the listener via the initialization through the configuration
  // It is used for main events (e.g., screen opened, button tapped).
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .setNoCodesListener(this)
  .build();

  // Set presentation style config before showing screen if needed
  const screenConfig = new ScreenPresentationConfig(ScreenPresentationStyle.FULL_SCREEN, true);
  NoCodes.getSharedInstance().setScreenPresentationConfig(screenConfig, 'yourContextKey');
  ```

  ```dart Flutter theme={null}
  // Set presentation style config before showing screen if needed
  final config = NoCodesPresentationConfig(
      animated: true,
      presentationStyle: NoCodesPresentationStyle.fullScreen,
  );

  NoCodes.getSharedInstance().setScreenPresentationConfig(config, contextKey: 'yourContextKey');

  // Subscribe to separate NoCodes event streams
  _screenShownStream = NoCodes.getSharedInstance().screenShownStream.listen((event) {
      // add functionality here
  });

  _finishedStream = NoCodes.getSharedInstance().finishedStream.listen((event) {
      // add functionality here
  });

  _actionStartedStream = NoCodes.getSharedInstance().actionStartedStream.listen((event) {
      // add functionality here
  });

  _actionFailedStream = NoCodes.getSharedInstance().actionFailedStream.listen((event) {
      // add functionality here
  });

  _actionFinishedStream = NoCodes.getSharedInstance().actionFinishedStream.listen((event) {
      // add functionality here
  });

  _screenFailedToLoadStream = NoCodes.getSharedInstance().screenFailedToLoadStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  // Set the delegate via the initialization through the configuration
  // It is used for main events (e.g., screen opened, button tapped).
  var noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .SetNoCodesDelegate(this)
      .Build();
  NoCodes.Initialize(noCodesConfig);

  // Set presentation style config before showing screen if needed
  var screenConfig = new ScreenPresentationConfig(ScreenPresentationStyle.FullScreen, true);
  NoCodes.GetSharedInstance().SetScreenPresentationConfig(screenConfig, "yourContextKey");
  ```

  ```typescript Cordova theme={null}
  // Set the listener via the initialization through the configuration
  // It is used for main events (e.g., screen opened, button tapped).
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder('projectKey')
    .setNoCodesListener(this)
  .build();

  // Set presentation style config before showing screen if needed
  const screenConfig = new Qonversion.ScreenPresentationConfig(Qonversion.ScreenPresentationStyle.FULL_SCREEN, true);
  Qonversion.NoCodes.getSharedInstance().setScreenPresentationConfig(screenConfig, 'yourContextKey');
  ```

  ```typescript Capacitor theme={null}
  // Set the listener via the initialization through the configuration
  // It is used for main events (e.g., screen opened, button tapped).
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .setNoCodesListener(this)
  .build();

  // Set presentation style config before showing screen if needed
  const screenConfig = new ScreenPresentationConfig(ScreenPresentationStyle.FULL_SCREEN, true);
  NoCodes.getSharedInstance().setScreenPresentationConfig(screenConfig, 'yourContextKey');
  ```
</CodeGroup>

After initializing the SDK, you can move forward and display the No-Codes screen:

<CodeGroup>
  ```swift Swift theme={null}
  NoCodes.shared.showScreen(withContextKey: "yourContextKey")
  ```

  ```kotlin Kotlin theme={null}
  NoCodes.shared.showScreen("yourContextKey")
  ```

  ```java Java theme={null}
  NoCodes.getSharedInstance().showScreen("yourContextKey");
  ```

  ```typescript React Native theme={null}
  NoCodes.getSharedInstance().showScreen('yourContextKey');
  ```

  ```dart Flutter theme={null}
  NoCodes.getSharedInstance().showScreen('yourContextKey');
  ```

  ```csharp Unity theme={null}
  NoCodes.GetSharedInstance().ShowScreen("yourContextKey");
  ```

  ```typescript Cordova theme={null}
  Qonversion.NoCodes.getSharedInstance().showScreen('yourContextKey');
  ```

  ```typescript Capacitor theme={null}
  NoCodes.getSharedInstance().showScreen('yourContextKey');
  ```
</CodeGroup>

<Info>
  If you want to use Qonversion No-Codes with your own purchase infrastructure, [see](using-no-codes-with-custom-purchases-handling) how you can do it in two simple steps.
</Info>

## Loading screens before presentation

By default, `showScreen` is fire-and-present: it presents a loading view immediately and fetches the content afterwards, so your app learns the outcome through delegate callbacks only after the screen is already on screen.

If you want to decide up front — an "ask-first" flow — use `loadScreen`. It awaits the screen's availability and data (from cache or network) *before* anything is presented, so you can either present the screen or show your own fallback UI without the SDK loading view ever appearing. A successful load warms the shared screens cache, so the following `showScreen` call with the same context key renders from cache.

<CodeGroup>
  ```swift Swift theme={null}
  do {
    _ = try await NoCodes.shared.loadScreen(withContextKey: "yourContextKey")  // warms the cache
    NoCodes.shared.showScreen(withContextKey: "yourContextKey")                // renders from cache
  } catch {
    presentOwnFallbackUI()                                                     // SDK screen never shown
  }
  ```

  ```kotlin Kotlin theme={null}
  // Kotlin coroutines
  lifecycleScope.launch {
    try {
      NoCodes.shared.loadScreen("yourContextKey")   // warms the cache
      NoCodes.shared.showScreen("yourContextKey")   // renders from cache
    } catch (e: NoCodesException) {
      presentOwnFallbackUi()                        // SDK screen never shown
    }
  }

  // Or the callback-based variant — the callback is invoked on the main thread
  NoCodes.shared.loadScreen("yourContextKey", object : NoCodesScreenLoadCallback {
    override fun onSuccess(screen: QNoCodeScreen) {
      NoCodes.shared.showScreen("yourContextKey")
    }

    override fun onError(error: NoCodesError) {
      presentOwnFallbackUi()
    }
  })
  ```

  ```java Java theme={null}
  // The callback is invoked on the main thread
  NoCodes.getSharedInstance().loadScreen("yourContextKey", new NoCodesScreenLoadCallback() {
    @Override
    public void onSuccess(@NonNull QNoCodeScreen screen) {
      NoCodes.getSharedInstance().showScreen("yourContextKey");
    }

    @Override
    public void onError(@NonNull NoCodesError error) {
      presentOwnFallbackUi();
    }
  });
  ```

  ```typescript React Native theme={null}
  try {
    const screen = await NoCodes.getSharedInstance().loadScreen('yourContextKey'); // warms the cache
    NoCodes.getSharedInstance().showScreen('yourContextKey');                      // renders from cache
  } catch (e) {
    presentOwnFallbackUi();                                                        // SDK screen never shown
  }
  ```

  ```dart Flutter theme={null}
  try {
    final screen = await NoCodes.getSharedInstance().loadScreen('yourContextKey'); // warms the cache
    NoCodes.getSharedInstance().showScreen('yourContextKey');                      // renders from cache
  } on QonversionException {
    presentOwnFallbackUi();                                                        // SDK screen never shown
  }
  ```

  ```csharp Unity theme={null}
  NoCodes.GetSharedInstance().LoadScreen(
      "yourContextKey",
      onSuccess: screen => NoCodes.GetSharedInstance().ShowScreen("yourContextKey"),
      onError: error => PresentOwnFallbackUi()
  );
  ```

  ```typescript Cordova theme={null}
  try {
    const screen = await Qonversion.NoCodes.getSharedInstance().loadScreen('yourContextKey');
    Qonversion.NoCodes.getSharedInstance().showScreen('yourContextKey');
  } catch (e) {
    presentOwnFallbackUi();
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const screen = await NoCodes.getSharedInstance().loadScreen('yourContextKey');
    NoCodes.getSharedInstance().showScreen('yourContextKey');
  } catch (e) {
    presentOwnFallbackUi();
  }
  ```
</CodeGroup>

The returned screen exposes its `id`, `contextKey`, and the typed default variables configured on it in the builder (see [Reading default variables](#reading-default-variables) below). The error lets you branch on the failure: a **screen not found** error (`NoCodesError.type == .screenNotFound` on iOS, error code `ScreenNotFound` on Android) means the screen is genuinely absent for that context key — show your fallback; any other code indicates a transient network or load failure — you may retry.

<Note>
  `loadScreen` is an optional, additional entry point — not a prerequisite for `showScreen`. Screens marked as preloadable in the No-Codes Builder are fetched automatically at SDK initialization (see [Screens Preloading](screens-preloading)), and `showScreen` works on its own.

  Two minor differences from a direct `showScreen` call: `loadScreen` does not flush pending user properties, so the targeting basis may differ slightly; and on-demand loads cache the screen without pre-embedded images (image embedding is applied during init-time preloading only).
</Note>

Available starting from the following SDK versions:

| Platform     | Minimum Version |
| ------------ | --------------- |
| iOS          | 6.13.0          |
| Android      | No-Codes 1.10.0 |
| React Native | 10.9.0          |
| Flutter      | 11.8.0          |
| Cordova      | 7.7.0           |
| Capacitor    | 1.6.0           |
| Unity        | 9.7.0           |

### Reading default variables

The screen returned by `loadScreen` carries the typed **default variables** configured on it in the No-Code Builder — `defaultVariables`. Each variable has a `kind`:

* **custom** — a Screen Variable authored in the builder's Variables section;
* **product** — a product slot: the variable key is the slot name and the value is the default Qonversion product ID assigned to it;
* **selectedProduct** — the screen's Default Product (Product Slots panel → Default Product): the Qonversion product ID selected by default when the screen opens. Read it via the typed shortcut `screen.defaultSelectedProductId` — no key needed.

Each variable preserves its configured native type (boolean / string / number) instead of being stringified:

<CodeGroup>
  ```swift Swift theme={null}
  public struct NoCodesScreenVariable {
    public let kind: NoCodesScreenVariableKind  // .custom, .product, .selectedProduct, or .unknown
    public let key: String    // variable name (`variable.<key>` in the builder) or slot name
    public let type: String   // "boolean", "string" or "number"
    public let value: NoCodesScreenVariableValue
  }

  public enum NoCodesScreenVariableValue {
    case bool(Bool)
    case string(String)
    case number(Double)
    case none                 // a null/absent configured default

    var stringValue: String { get }  // any value as a plain string ("" for none)
  }
  ```

  ```kotlin Kotlin theme={null}
  data class QScreenVariable(
    val kind: Kind,                  // Custom, Product, SelectedProduct, or Unknown
    val key: String,                 // variable name (`variable.<key>` in the builder) or slot name
    val type: String,                // "boolean", "string" or "number"
    val value: QScreenVariableValue, // Bool / Str / Num / None — preserves the native type
  )

  // QScreenVariableValue.asString(): any value as a plain string ("" for None)
  ```
</CodeGroup>

For example, to read a variable by key, the default product of a slot, and the screen's default selected product. Keys are only unique within a kind — a custom variable and a product slot may share a name — so the by-key lookup accepts an optional kind filter:

<CodeGroup>
  ```swift Swift theme={null}
  let screen = try await NoCodes.shared.loadScreen(withContextKey: "yourContextKey")

  if case .bool(let showTrial) = screen.defaultVariable(forKey: "show_trial", kind: .custom)?.value {
    print("show_trial = \(showTrial)")
  }

  let primarySlotProduct = screen.defaultVariable(forKey: "primary", kind: .product)?.value.stringValue
  let defaultSelected = screen.defaultSelectedProductId
  ```

  ```kotlin Kotlin theme={null}
  val screen = NoCodes.shared.loadScreen("yourContextKey")

  val showTrial = (screen.defaultVariable("show_trial", QScreenVariable.Kind.Custom)?.value
      as? QScreenVariableValue.Bool)?.value ?: false

  val primarySlotProduct = screen.defaultVariable("primary", QScreenVariable.Kind.Product)?.value?.asString()
  val defaultSelected = screen.defaultSelectedProductId
  ```
</CodeGroup>

<Info>
  `defaultVariables` is an empty list when the screen has none configured (or on older payloads), so it is always safe to iterate. The `kind` set may grow — values unknown to your SDK version arrive as `.unknown` / `Unknown` instead of failing the load.
</Info>

<Note>
  These values are the **defaults configured on the screen**, read back at load time. Conditional slot overrides and runtime mutations inside the running screen are not reflected, and they are not the same as the custom variables you pass *into* a screen from your app (see [Passing custom variables](#passing-custom-variables)).
</Note>

## Passing custom variables

You can pass dynamic values from your app into a No-Code screen and reference them in conditional logic, dynamic text, or component visibility rules. Variables are scoped to a specific `contextKey`, so different screens can receive different values, and each value is queried at the moment a screen is about to be shown — including sub-screens reached via in-screen navigation.

For native SDKs, implement a delegate that returns a `Map`/dictionary keyed by `contextKey`. For cross-platform SDKs, pass the values directly to `showScreen`.

<CodeGroup>
  ```swift Swift theme={null}
  // 1. Implement NoCodesCustomVariablesDelegate
  extension MyClass: NoCodesCustomVariablesDelegate {
    func customVariables(for contextKey: String) -> [String: String] {
      return ["button_color": "red", "username": "Alex"]
    }
  }

  // 2. Provide it to the SDK
  NoCodes.shared.set(customVariablesDelegate: self)
  // Or via configuration:
  let configuration = NoCodesConfiguration(projectKey: "projectKey", customVariablesDelegate: self)
  ```

  ```kotlin Kotlin theme={null}
  // 1. Implement CustomVariablesDelegate
  class MyActivity : AppCompatActivity(), CustomVariablesDelegate {
    override fun getCustomVariables(contextKey: String): Map<String, String> {
      return mapOf("button_color" to "red", "username" to "Alex")
    }
  }

  // 2. Provide it to the SDK
  NoCodes.shared.setCustomVariablesDelegate(this)
  // Or via configuration:
  val noCodesConfig = NoCodesConfig.Builder(this, "projectKey")
    .setCustomVariablesDelegate(this)
    .build()
  ```

  ```java Java theme={null}
  // 1. Implement CustomVariablesDelegate
  public class MyActivity extends AppCompatActivity implements CustomVariablesDelegate {
    @NonNull
    @Override
    public Map<String, String> getCustomVariables(@NonNull String contextKey) {
      Map<String, String> variables = new HashMap<>();
      variables.put("button_color", "red");
      variables.put("username", "Alex");
      return variables;
    }
  }

  // 2. Provide it to the SDK
  NoCodes.getSharedInstance().setCustomVariablesDelegate(this);
  // Or via configuration:
  final NoCodesConfig noCodesConfig = new NoCodesConfig.Builder(this, "projectKey")
    .setCustomVariablesDelegate(this)
    .build();
  ```

  ```typescript React Native theme={null}
  const customVariables = { button_color: 'red', username: 'Alex' };
  NoCodes.getSharedInstance().showScreen('yourContextKey', customVariables);
  ```

  ```dart Flutter theme={null}
  final customVariables = {'button_color': 'red', 'username': 'Alex'};
  NoCodes.getSharedInstance().showScreen('yourContextKey', customVariables: customVariables);
  ```

  ```csharp Unity theme={null}
  var customVariables = new Dictionary<string, string> {
    { "button_color", "red" },
    { "username", "Alex" }
  };
  NoCodes.GetSharedInstance().ShowScreen("yourContextKey", customVariables);
  ```

  ```typescript Cordova theme={null}
  const customVariables = { button_color: 'red', username: 'Alex' };
  Qonversion.NoCodes.getSharedInstance().showScreen('yourContextKey', customVariables);
  ```

  ```typescript Capacitor theme={null}
  const customVariables = { button_color: 'red', username: 'Alex' };
  NoCodes.getSharedInstance().showScreen('yourContextKey', customVariables);
  ```
</CodeGroup>

<Info>
  Values must be strings. Inside the screen, variables are injected into the JavaScript context via `window.noCodesSetVariable(name, value)` and then become available in conditional logic, dynamic text bindings, and visibility rules.
</Info>

## Delegates

Earlier, we discussed how to set delegates. Now, let's explore their purpose.

### Main delegate

The main delegate is needed so that you can receive messages about what is happening during the execution of No-Codes, as well as to provide us with the screen from which to start navigation and display the No-Codes screen. Let's go through this step by step.

<Warning>
  ### Unity Warning

  Unity NoCodes delegate events are delivered on iOS only. On Android, the No-Codes screen runs as a separate Activity on top of Unity's Activity and Unity's game loop is paused while the screen is shown, so delegate events do not fire.
</Warning>

##### controllerForNavigation *(iOS only)*

<CodeGroup>
  ```swift Swift theme={null}
  func controllerForNavigation() -> UIViewController?
  ```
</CodeGroup>

In this function, you must return a UIViewController from which we will start displaying the No-Codes flow. If you do not provide one, we will take the topmost screen in the current stack.

##### Screen shown event

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesHasShownScreen(id: String)
  ```

  ```kotlin Kotlin theme={null}
  fun onScreenShown(screenId: String)
  ```

  ```java Java theme={null}
  void onScreenShown(String screenId)
  ```

  ```typescript React-Native theme={null}
  onScreenShown: (id: string) => {}
  ```

  ```dart Flutter theme={null}
  _screenShownStream = NoCodes.getSharedInstance().screenShownStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  void OnScreenShown(string contextKey)
  ```

  ```typescript Cordova theme={null}
  onScreenShown: (id: string) => {}
  ```

  ```typescript Capacitor theme={null}
  onScreenShown: (id: string) => {}
  ```
</CodeGroup>

This function notifies about the display of a screen with a specific identifier.

<Note>
  To read the screen's configured default variables and product slots, load the screen entity via `loadScreen` and use its `defaultVariables` — see [Reading default variables](#reading-default-variables).
</Note>

#### Action execution start event

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesStartsExecuting(action: NoCodesAction)
  ```

  ```kotlin Kotlin theme={null}
  fun onActionStartedExecuting(action: QAction)
  ```

  ```java Java theme={null}
  void onActionStartedExecuting(QAction action)
  ```

  ```typescript React-Native theme={null}
  onActionStartedExecuting: (action: NoCodesAction) => {}
  ```

  ```dart Flutter theme={null}
  _actionStartedStream = NoCodes.getSharedInstance().actionStartedStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  void OnActionStarted(NoCodesAction action)
  ```

  ```typescript Cordova theme={null}
  onActionStartedExecuting: (action: Qonversion.NoCodesAction) => {}
  ```

  ```typescript Capacitor theme={null}
  onActionStartedExecuting: (action: NoCodesAction) => {}
  ```
</CodeGroup>

This function notifies you that executing the action you set up through our dashboard has begun.

#### Action execution fail event

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesFailedToExecute(action: NoCodesAction, error: Error?)
  ```

  ```kotlin Kotlin theme={null}
  fun onActionFailedToExecute(action: QAction) {
    // For details look at the `error` property of the action
  }
  ```

  ```java Java theme={null}
  void onActionFailedToExecute(QAction action) {
    // For details look at the `error` property of the action
  }
  ```

  ```typescript React-Native theme={null}
  onActionFailedToExecute: (action: NoCodesAction) => {}
  ```

  ```dart Flutter theme={null}
  _actionFailedStream = NoCodes.getSharedInstance().actionFailedStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  void OnActionFailed(NoCodesAction action)
  ```

  ```typescript Cordova theme={null}
  onActionFailedToExecute: (action: Qonversion.NoCodesAction) => {}
  ```

  ```typescript Capacitor theme={null}
  onActionFailedToExecute: (action: NoCodesAction) => {}
  ```
</CodeGroup>

This function notifies you that executing the action you set up through our dashboard has failed.

#### Action execution finish event

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesFinishedExecuting(action: NoCodesAction)
  ```

  ```kotlin Kotlin theme={null}
  fun onActionFinishedExecuting(action: QAction)
  ```

  ```java Java theme={null}
  void onActionFinishedExecuting(QAction action)
  ```

  ```typescript React-Native theme={null}
  onActionFinishedExecuting: (action: NoCodesAction) => {}
  ```

  ```dart Flutter theme={null}
  _actionFinishedStream = NoCodes.getSharedInstance().actionFinishedStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  void OnActionFinished(NoCodesAction action)
  ```

  ```typescript Cordova theme={null}
  onActionFinishedExecuting: (action: Qonversion.NoCodesAction) => {}
  ```

  ```typescript Capacitor theme={null}
  onActionFinishedExecuting: (action: NoCodesAction) => {}
  ```
</CodeGroup>

This function notifies you that the action you set up through our dashboard has been executed.

#### Custom action received event

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesReceivedCustomAction(value: String)
  ```

  ```kotlin Kotlin theme={null}
  fun onCustomAction(value: String)
  ```

  ```java Java theme={null}
  void onCustomAction(String value)
  ```

  ```typescript React Native theme={null}
  onCustomAction: (value: string) => {}
  ```

  ```dart Flutter theme={null}
  _customActionStream = NoCodes.getSharedInstance().customActionStream.listen((event) {
      // event.value identifies the triggered action
  });
  ```

  ```csharp Unity theme={null}
  // Implement the optional NoCodesCustomActionDelegate interface alongside your NoCodesDelegate
  void OnCustomAction(string value)
  ```

  ```typescript Cordova theme={null}
  onCustomAction: (value: string) => {}
  ```

  ```typescript Capacitor theme={null}
  onCustomAction: (value: string) => {}
  ```
</CodeGroup>

This function is called when a <a href="/docs/custom-actions">Custom action</a> is triggered on the screen. Custom actions are not executed by the SDK — implement your own handling here; the `value` string configured in the builder identifies which action was triggered. The screen stays open; close it using `NoCodes.shared.close()` if needed. If no value was configured, an empty string is delivered.

Available starting from the following SDK versions:

| Platform     | Minimum Version |
| ------------ | --------------- |
| iOS          | 6.13.0          |
| Android      | No-Codes 1.10.0 |
| React Native | 10.9.0          |
| Flutter      | 11.8.0          |
| Cordova      | 7.7.0           |
| Capacitor    | 1.6.0           |
| Unity        | 9.7.0           |

#### Screen finished event

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesFinished()
  ```

  ```kotlin Kotlin theme={null}
  fun onFinished()
  ```

  ```java Java theme={null}
  void onFinished()
  ```

  ```typescript React-Native theme={null}
  onFinished: () => {}
  ```

  ```dart Flutter theme={null}
  _finishedStream = NoCodes.getSharedInstance().finishedStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  void OnFinished()
  ```

  ```typescript Cordova theme={null}
  onFinished: () => {}
  ```

  ```typescript Capacitor theme={null}
  onFinished: () => {}
  ```
</CodeGroup>

This function notifies that the No-Codes flow has been completed and No-Codes has been finished.

#### Screen loading failed

<CodeGroup>
  ```swift Swift theme={null}
  func noCodesFailedToLoadScreen(error: Error?)
  ```

  ```kotlin Kotlin theme={null}
  fun onScreenFailedToLoad(error: NoCodesError)
  ```

  ```java Java theme={null}
  void onScreenFailedToLoad(NoCodesError error)
  ```

  ```typescript React-Native theme={null}
  onScreenFailedToLoad: (error: NoCodesError) => {}
  ```

  ```dart Flutter theme={null}
  _screenFailedToLoadStream = NoCodes.getSharedInstance().screenFailedToLoadStream.listen((event) {
      // add functionality here
  });
  ```

  ```csharp Unity theme={null}
  void OnScreenFailedToLoad(NoCodesError error)
  ```

  ```typescript Cordova theme={null}
  onScreenFailedToLoad: (error: Qonversion.NoCodesError) => {}
  ```

  ```typescript Capacitor theme={null}
  onScreenFailedToLoad: (error: NoCodesError) => {}
  ```
</CodeGroup>

This function is called when No-Codes screen loading has failed.

### Localization

By default, No-Code screens automatically detect the device's system language and display the appropriate localization if available. You can override this behavior by setting a custom locale, which takes priority over the automatic system language detection.

The locale should be in standard format (e.g., `"en"`, `"en-US"`, `"de"`, `"de-DE"`). Pass `nil`/`null` to reset to the system default locale.

**Setting locale during initialization:**

<CodeGroup>
  ```swift Swift theme={null}
  var config = NoCodesConfiguration(
      projectKey: "your_project_key",
      locale: "de-DE"
  )
  NoCodes.initialize(with: config)
  ```

  ```kotlin Kotlin theme={null}
  val config = NoCodesConfig.Builder(context, "your_project_key")
      .setLocale("de-DE")
      .build()
  NoCodes.initialize(config)
  ```

  ```java Java theme={null}
  NoCodesConfig config = new NoCodesConfig.Builder(context, "your_project_key")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(config);
  ```

  ```typescript React Native theme={null}
  const noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```dart Flutter theme={null}
  final noCodesConfig = NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```csharp Unity theme={null}
  var noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .SetLocale("de-DE")
      .Build();
  NoCodes.Initialize(noCodesConfig);
  ```

  ```typescript Cordova theme={null}
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  Qonversion.NoCodes.initialize(noCodesConfig);
  ```

  ```typescript Capacitor theme={null}
  const noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .setLocale("de-DE")
      .build();
  NoCodes.initialize(noCodesConfig);
  ```
</CodeGroup>

**Setting locale after initialization:**

<CodeGroup>
  ```swift Swift theme={null}
  NoCodes.shared.setLocale("fr-FR")
  NoCodes.shared.showScreen(withContextKey: "your_context_key")

  // Reset to system default
  NoCodes.shared.setLocale(nil)
  ```

  ```kotlin Kotlin theme={null}
  NoCodes.shared.setLocale("fr-FR")
  NoCodes.shared.showScreen("your_context_key")

  // Reset to system default
  NoCodes.shared.setLocale(null)
  ```

  ```java Java theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("your_context_key");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```

  ```typescript React Native theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```

  ```dart Flutter theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```

  ```csharp Unity theme={null}
  NoCodes.GetSharedInstance().SetLocale("fr-FR");
  NoCodes.GetSharedInstance().ShowScreen("yourContextKey");

  // Reset to system default
  NoCodes.GetSharedInstance().SetLocale(null);
  ```

  ```typescript Cordova theme={null}
  Qonversion.NoCodes.getSharedInstance().setLocale("fr-FR");
  Qonversion.NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  Qonversion.NoCodes.getSharedInstance().setLocale(null);
  ```

  ```typescript Capacitor theme={null}
  NoCodes.getSharedInstance().setLocale("fr-FR");
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to system default
  NoCodes.getSharedInstance().setLocale(null);
  ```
</CodeGroup>

### Theme

No-Code screens support light and dark themes. By default, screens automatically adapt to the device's system appearance (Auto mode). You can override this behavior by setting a specific theme, which takes priority over the automatic system theme detection.

<Warning>
  Currently, the theme only affects skeleton loader colors, with full theming support for the No-Code Builder coming soon
</Warning>

Available theme modes:

* **Auto** (default) - Follows the device's system appearance
* **Light** - Forces light theme regardless of device settings
* **Dark** - Forces dark theme regardless of device settings

**Setting theme during initialization:**

<CodeGroup>
  ```swift Swift theme={null}
  var config = NoCodesConfiguration(
      projectKey: "your_project_key",
      theme: .dark
  )
  NoCodes.initialize(with: config)
  ```

  ```kotlin Kotlin theme={null}
  val config = NoCodesConfig.Builder(context, "your_project_key")
      .setTheme(NoCodesTheme.Dark)
      .build()
  NoCodes.initialize(config)
  ```

  ```java Java theme={null}
  NoCodesConfig config = new NoCodesConfig.Builder(context, "your_project_key")
      .setTheme(NoCodesTheme.Dark)
      .build();
  NoCodes.initialize(config);
  ```

  ```typescript React Native theme={null}
  const noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .setTheme(NoCodesTheme.DARK)
      .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```dart Flutter theme={null}
  final noCodesConfig = NoCodesConfigBuilder("projectKey")
      .setTheme(NoCodesTheme.dark)
      .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```csharp Unity theme={null}
  var noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .SetTheme(NoCodesTheme.Dark)
      .Build();
  NoCodes.Initialize(noCodesConfig);
  ```

  ```typescript Cordova theme={null}
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder("projectKey")
      .setTheme(Qonversion.NoCodesTheme.DARK)
      .build();
  Qonversion.NoCodes.initialize(noCodesConfig);
  ```

  ```typescript Capacitor theme={null}
  const noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .setTheme(NoCodesTheme.DARK)
      .build();
  NoCodes.initialize(noCodesConfig);
  ```
</CodeGroup>

**Setting theme after initialization:**

<CodeGroup>
  ```swift Swift theme={null}
  NoCodes.shared.setTheme(.light)
  NoCodes.shared.showScreen(withContextKey: "your_context_key")

  // Reset to auto (follow system appearance)
  NoCodes.shared.setTheme(.auto)
  ```

  ```kotlin Kotlin theme={null}
  NoCodes.shared.setTheme(NoCodesTheme.Light)
  NoCodes.shared.showScreen("your_context_key")

  // Reset to auto (follow system appearance)
  NoCodes.shared.setTheme(NoCodesTheme.Auto)
  ```

  ```java Java theme={null}
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.Light);
  NoCodes.getSharedInstance().showScreen("your_context_key");

  // Reset to auto (follow system appearance)
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.Auto);
  ```

  ```typescript React Native theme={null}
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.LIGHT);
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to auto (follow system appearance)
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.AUTO);
  ```

  ```dart Flutter theme={null}
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.light);
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to auto (follow system appearance)
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.auto);
  ```

  ```csharp Unity theme={null}
  NoCodes.GetSharedInstance().SetTheme(NoCodesTheme.Light);
  NoCodes.GetSharedInstance().ShowScreen("yourContextKey");

  // Reset to auto (follow system appearance)
  NoCodes.GetSharedInstance().SetTheme(NoCodesTheme.Auto);
  ```

  ```typescript Cordova theme={null}
  Qonversion.NoCodes.getSharedInstance().setTheme(Qonversion.NoCodesTheme.LIGHT);
  Qonversion.NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to auto (follow system appearance)
  Qonversion.NoCodes.getSharedInstance().setTheme(Qonversion.NoCodesTheme.AUTO);
  ```

  ```typescript Capacitor theme={null}
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.LIGHT);
  NoCodes.getSharedInstance().showScreen("yourContextKey");

  // Reset to auto (follow system appearance)
  NoCodes.getSharedInstance().setTheme(NoCodesTheme.AUTO);
  ```
</CodeGroup>

### Screen customization

Use the screen customization delegate to customize the screen opening animation. For example, to enable or disable the animation (*iOS only*), specify the type of opening: push/popover (*iOS only*)/full screen. You can also pass a `statusBarHidden` flag that determines whether to show or hide the status bar when displaying the screen (*iOS only*).

For example:

<CodeGroup>
  ```swift Swift theme={null}
  func presentationConfigurationForScreen(contextKey: String) -> NoCodesPresentationConfiguration {
    return NoCodesPresentationConfiguration(animated: true, presentationStyle: .push)
  }
  ```

  ```kotlin Kotlin theme={null}
  override fun getPresentationConfigurationForScreen(contextKey: String): QScreenPresentationConfig {
    return QScreenPresentationConfig(QScreenPresentationStyle.Push)
  }
  ```

  ```java Java theme={null}
  @NonNull
  @Override
  public QScreenPresentationConfig getPresentationConfigurationForScreen(@NonNull String contextKey) {
    return new QScreenPresentationConfig(QScreenPresentationStyle.Push);
  }
  ```

  ```typescript React-Native theme={null}
  // Set presentation style config before showing screen if needed
  const screenConfig = new ScreenPresentationConfig(ScreenPresentationStyle.FULL_SCREEN, true);

  NoCodes.getSharedInstance().setScreenPresentationConfig(screenConfig, 'yourContextKey');
  ```

  ```dart Flutter theme={null}
  // Set presentation style config before showing screen if needed
  final config = NoCodesPresentationConfig(
      animated: true,
      presentationStyle: NoCodesPresentationStyle.fullScreen,
  );

  NoCodes.getSharedInstance().setScreenPresentationConfig(config, contextKey: 'yourContextKey');
  ```

  ```csharp Unity theme={null}
  // Set presentation style config before showing screen if needed
  var screenConfig = new ScreenPresentationConfig(ScreenPresentationStyle.FullScreen, true);

  NoCodes.GetSharedInstance().SetScreenPresentationConfig(screenConfig, "yourContextKey");
  ```

  ```typescript Cordova theme={null}
  // Set presentation style config before showing screen if needed
  const screenConfig = new Qonversion.ScreenPresentationConfig(Qonversion.ScreenPresentationStyle.FULL_SCREEN, true);

  Qonversion.NoCodes.getSharedInstance().setScreenPresentationConfig(screenConfig, 'yourContextKey');
  ```

  ```typescript Capacitor theme={null}
  // Set presentation style config before showing screen if needed
  const screenConfig = new ScreenPresentationConfig(ScreenPresentationStyle.FULL_SCREEN, true);

  NoCodes.getSharedInstance().setScreenPresentationConfig(screenConfig, 'yourContextKey');
  ```
</CodeGroup>

### Custom loading view

By default, the SDK displays a skeleton loading view while the No-Code screen is loading. You can replace it with your own custom loading view by implementing the `noCodesCustomLoadingView()` method in the screen customization delegate.

Your custom view must conform to the `NoCodesLoadingView` protocol (iOS) or implement the `NoCodesLoadingView` interface (Android). The SDK calls `startAnimating()` when the loading begins and `stopAnimating()` when the screen content is ready.

<CodeGroup>
  ```swift Swift theme={null}
  // Conform to NoCodesLoadingView
  class MyLoadingView: UIView, NoCodesLoadingView {
    func startAnimating() {
      // Start your loading animation
    }

    func stopAnimating() {
      // Stop your loading animation
    }
  }

  // Return it from the screen customization delegate
  func noCodesCustomLoadingView() -> NoCodesLoadingView? {
    return MyLoadingView(frame: .zero)
  }
  ```

  ```kotlin Kotlin theme={null}
  // Implement NoCodesLoadingView
  class MyLoadingView(context: Context) : FrameLayout(context), NoCodesLoadingView {
    override fun startAnimating() {
      // Start your loading animation
    }

    override fun stopAnimating() {
      // Stop your loading animation
    }
  }

  // Return it from the screen customization delegate
  override fun noCodesCustomLoadingView(): View? {
    return MyLoadingView(context)
  }
  ```

  ```java Java theme={null}
  // Implement NoCodesLoadingView
  public class MyLoadingView extends FrameLayout implements NoCodesLoadingView {
    @Override
    public void startAnimating() {
      // Start your loading animation
    }

    @Override
    public void stopAnimating() {
      // Stop your loading animation
    }
  }

  // Return it from the screen customization delegate
  @Nullable
  @Override
  public View noCodesCustomLoadingView() {
    return new MyLoadingView(context);
  }
  ```
</CodeGroup>

<Info>
  If `noCodesCustomLoadingView()` returns `nil` / `null`, the default skeleton loading view will be used.
</Info>

***

[Screens Preloading](screens-preloading)

[Success and Failure Actions](success-failure-actions)


# How to display products with the Qonversion SDK
Source: https://documentation.qonversion.io/docs/displaying-products

Fetch cross-platform Qonversion Products with the SDK, read every field of the Product object, and check a user's trial and introductory offer eligibility on iOS and Android.

The Qonversion SDK manages in-app purchases across platforms so you do not store App Store or Google Play product IDs and prices on the client. To promote products from the Qonversion dashboard, first [configure Products and Entitlements](subscription-management-mode#1-configure-products--entitlements) in Qonversion.

Qonversion gives you two ways to decide which products to show:

* **Remote Config (recommended)** — a [Remote Config](remote-config) holds your product IDs, so you can change the products offered, target user segments, and [run A/B tests](launch-test-from-remote-config) without an app release. See the [recommended payload structure and code samples](migrate-offerings-to-remote-configs).
* **Qonversion Products directly** — fetch the full list of configured products with the SDK, as described in [Get the list of available products](#get-the-list-of-available-products) below.

<Check>
  ### Local cache

  The [Qonversion SDK caches product and entitlement data](offline-sdk-mode), so the list stays available when the internet connection is lost or the server is delayed. On every app launch the SDK also requests the current `SKProduct` / `storeDetails` from the App Store or Google Play to keep prices and product data up to date.
</Check>

## Get the list of available products

Call the `products` method to fetch every product configured for your project. The method returns a dictionary keyed by Qonversion Product ID; each value is a `Qonversion.Product` object.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().products { productsList, error in
      let product = productsList["main"]
      if product?.type == .trial {

      }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] products:^(NSDictionary<NSString *,QONProduct *> * _Nonnull productsList, NSError * _Nullable error) {
    if (error) {
      // Handle error
    }
    QONProduct *product = productsList[@"main"];
    if (product && product.type == QONProductTypeTrial) {

    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().products(new QonversionProductsCallback() {
              @Override
              public void onSuccess(@NotNull Map<String, QProduct> productsList) {
                  // handle available products here
              }

              @Override
              public void onError(@NotNull QonversionError error) {
                  // handle error here
              }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.products(callback = object: QonversionProductsCallback {
              override fun onSuccess(products: Map<String, QProduct>) {
                  // handle available products here
              }

              override fun onError(error: QonversionError) {
                  // handle error here
              }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QProduct> products = await Qonversion.getSharedInstance().products();
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  const products: Map<string, Product> = await Qonversion.getSharedInstance().products();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Products((products, error) =>
  {
     if (error == null)
     {
         // Display products
     }
     else
     {
         // Handle the error
         Debug.Log("Error" + error.ToString());
     }
  });
  ```

  ```typescript Cordova theme={null}
  const products = await Qonversion.getSharedInstance().products();
  ```

  ```typescript Capacitor theme={null}
  const products: Map<string, Product> = await Qonversion.getSharedInstance().products();
  ```
</CodeGroup>

The callback (or return value) provides:

* `productsList` — a dictionary of available products, keyed by Qonversion Product ID (for example, `main`). Values are `Qonversion.Product` objects.
* `error` — the error, if the request failed. On callback-based platforms the products dictionary is empty when `error` is set.

The `products` method returns only products you configured in the Qonversion dashboard. It does not create products in the stores, and it does not return App Store or Google Play products that are not linked to a Qonversion Product.

## The Product object

`Qonversion.Product` exposes the fields below. Fields marked *iOS only* or *Android only* are `nil`/`null` on the other platform.

| Property             | Type / values                                                                  | Description                                                                                                                                                                                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qonversionID`       | String                                                                         | Qonversion Product ID. For example, `main`.                                                                                                                                                                                                                                                                                              |
| `storeID`            | String                                                                         | The store product ID (App Store or Google Play).                                                                                                                                                                                                                                                                                         |
| `basePlanID`         | String, *Android only*                                                         | Identifier of the base plan for a subscription product.                                                                                                                                                                                                                                                                                  |
| `type`               | Enum: `trial`, `intro`, `directSubscription`/`subscription`, `oneTime`/`inapp` | Product type. `trial` — subscription with a trial period; `intro` — subscription with an intro period; `directSubscription`/`subscription` — auto-renewable or prepaid (Android) subscription without a trial or intro; `oneTime`/`inapp` — non-recurring product.                                                                       |
| `subscriptionPeriod` | `SubscriptionPeriod` object, or `nil` if not a subscription                    | The subscription period. `SubscriptionPeriod` has `SubscriptionPeriodUnit` (`day`, `week`, `month`, or `year`) and an integer `unitCount`. For example, `unit = .month` and `unitCount = 3` means a 3-month subscription. On Android and cross-platform SDKs it also has an `iso` field in ISO 8601 format, e.g. `P3M` for that example. |
| `trialPeriod`        | `SubscriptionPeriod` object, or `nil` if not a subscription or no trial        | The trial period. Same shape as `subscriptionPeriod`. For example, `unit = .day` and `unitCount = 7` means a 7-day trial. On Android and cross-platform SDKs it also has an `iso` field, e.g. `P3M`.                                                                                                                                     |
| `skProduct`          | `SKProduct`, *iOS only*                                                        | The `SKProduct` object received from StoreKit.                                                                                                                                                                                                                                                                                           |
| `storeDetails`       | Store details object, *Android only*                                           | The Google Play store details of the product, including the offers for purchasing the base plan (specified by `basePlanID`) for a subscription. Full description: [Google Play product details](google-play-product-details).                                                                                                            |
| `prettyPrice`        | String                                                                         | A localized price with currency symbol from Apple or Google, ready to display. For example, `$99.99`.                                                                                                                                                                                                                                    |

<Accordion title="Deprecated fields" icon="triangle-exclamation">
  **These fields are deprecated. Use the replacement field listed for each — new integrations should not read these.**

  | Property        | Type / values                                                                                                                                   | Status                                     | Description                                                                                                                                                                                |
  | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `duration`      | Enum: `unknown`, `weekly`, `monthly`, `3Months`, `6Months`, `annual`, *iOS only*                                                                | **Deprecated — use `subscriptionPeriod`.** | Duration of a product. `unknown` — non-renewable purchases. There is no 2-month option because Google Play does not have it.                                                               |
  | `trialDuration` | Enum: `notAvailable`, `unknown`, `threeDays`, `week`, `twoWeeks`, `month`, `twoMonths`, `threeMonths`, `sixMonths`, `year`, `other`, *iOS only* | **Deprecated — use `trialPeriod`.**        | Duration of an introductory offer. `notAvailable` — trial not available; `unknown` — no trial info; `other` — duration outside the enum range, check `skuDetails` or `skProduct` directly. |
  | `skuDetail`     | `skuDetails` object, *Android only*                                                                                                             | **Deprecated — use `storeDetails`.**       | The `skuDetails` object received from the Google Billing Client.                                                                                                                           |
</Accordion>

## How to check trial and introductory offer eligibility

You can check whether a user is eligible for an introductory offer, including a free trial, before showing a price. Eligibility is computed differently per platform:

* **iOS** — a user is eligible if they have not previously used an introductory offer for any product in the same subscription group.
* **Android** — eligibility is computed from the store details. If the Google Play Billing Library returns any trial or intro offer as a possible purchase option for a product, the user is eligible for it.

Show only the regular price to users who are not eligible for an introductory offer. Use `checkTrialIntroEligibility` to determine eligibility:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().checkTrialIntroEligibility(["main", "secondary"]) { (result, error) in
    if let mainProductIntroEligibility = result["main"],
       mainProductIntroEligibility.status == .eligible {
       // handle available trial
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] checkTrialIntroEligibility:@[@"main", @"secondary"] completion:^(NSDictionary<NSString *,QNIntroEligibility *> * _Nonnull result, NSError * _Nullable error) {
    QONIntroEligibility *mainProductEligibility = result[@"main"];
    if (mainProductEligibility && mainProductEligibility.status == QONIntroEligibilityStatusEligible) {
      // handle available trial
    }
  }];
  ```

  ```java Java theme={null}
  List<String> productIds = Arrays.asList("main", "secondary");
  Qonversion.getSharedInstance().checkTrialIntroEligibility(productIds, new QonversionEligibilityCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEligibility> eligibilities) {
          QEligibility mainProductEligibility = eligibilities.get("main");
          if (mainProductEligibility != null && mainProductEligibility.getStatus() == QIntroEligibilityStatus.Eligible) {
              // handle available trial
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.checkTrialIntroEligibility(listOf("main", "secondary"), object : QonversionEligibilityCallback {
      override fun onSuccess(eligibilities: Map<String, QEligibility>) {
          val mainProductEligibility = eligibilities["main"];
          if (mainProductEligibility != null && mainProductEligibility.status == QIntroEligibilityStatus.Eligible) {
              // handle result here
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEligibility> eligibility = await Qonversion.getSharedInstance().checkTrialIntroEligibility(['main', 'premium']);
    final QEligibility mainProductStatus = eligibility['main'];
    if (mainProductStatus.status == QEligibilityStatus.eligible) {
        // handle available trial
    }
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
      const eligibilityStatuses = await Qonversion.getSharedInstance().checkTrialIntroEligibility(['main', 'secondary']);
      const mainProductEligibility = eligibilityStatuses.get('main');
      if (mainProductEligibility && mainProductEligibility.status === IntroEligibilityStatus.ELIGIBLE) {
          // handle result here
      }
  } catch (error) {
      // handle error here
  }
  ```

  ```csharp Unity theme={null}
  string[] productIds = {"premium"};

  Qonversion.GetSharedInstance().CheckTrialIntroEligibility(productIds, (eligibility, error) =>
  {
      if (error == null)
      {
          if (eligibility.TryGetValue("premium", out Eligibility premiumEligibility) && premiumEligibility.Status == EligibilityStatus.Eligible)
          {
              // handle available eligibility
          }
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const eligibilityStatuses = await Qonversion.getSharedInstance().checkTrialIntroEligibility(['main', 'secondary']);
      const mainProductEligibility = eligibilityStatuses.get('main');
      if (mainProductEligibility && mainProductEligibility.status === Qonversion.IntroEligibilityStatus.ELIGIBLE) {
          // handle result here
      }
  } catch (error) {
      // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
      const eligibilityStatuses = await Qonversion.getSharedInstance().checkTrialIntroEligibility(['main', 'secondary']);
      const mainProductEligibility = eligibilityStatuses.get('main');
      if (mainProductEligibility && mainProductEligibility.status === IntroEligibilityStatus.ELIGIBLE) {
          // handle result here
      }
  } catch (error) {
      // handle error here
  }
  ```
</CodeGroup>


# Edit Entitlements
Source: https://documentation.qonversion.io/docs/edit-entitlements

Grant users premium content access manually without a purchase, via the Qonversion dashboard or REST API, for testing, support, or promotions.

## Granting Entitlements

With the **"Edit entitlements"** button in Qonversion, you can grant users access to premium content for a specified duration without requiring a purchase or promo code. This feature proves valuable in many scenarios, such as offering beta users a free preview of content or effectively addressing customer support concerns.

1. Navigate to the [Customers](https://dash.qonversion.io/customers/) tab
2. Click on the customer whose entitlements you want to configure
3. Click the "+ Add" button to select a specific entitlement and the duration of time for which it will be active for this customer

<Info>
  Granted entitlements will be displayed in the API response with the "manual" source and will not have any particular event in the Events tab.
</Info>

<img alt="" />

<Info>
  ### REST API Entitlements

  Manage premium user access through the REST API endpoint - see [Grant Entitlement](/api-reference/entitlements/grant-an-entitlement) in the API Reference. **Requires Secret Key authentication.**
</Info>

***

## Removing Granted Entitlement

Granted entitlements will automatically be removed after expiration. To remove them early:

1. Navigate to the user profile at the [Customers](https://dash.qonversion.io/customers/) tab
2. Locate the entitlement you wish to delete from the list of granted entitlements.
3. Identify the "Delete" button associated with the specific entitlement and click on it.
4. Confirm the deletion when prompted to ensure that the entitlement is permanently removed.

<img alt="" />

***

[Customers](customers)

[Customer Details](customer-details)


# Enable Refund Keeper
Source: https://documentation.qonversion.io/docs/enable-refund-keeper

A short guide on how to Enable Refund Keeper in Qonversion and start saving revenue today.

Before enabling **Refund Keeper**, don't forget to make sure you're compliant with [requirements](refund-keeper#requirements-to-use-refund-keeper)

***

1. **Open [Refund Keeper](https://dash.qonversion.io/refund-keeper) Section in Qonversion**
2. **Enable App Store Server-to-Server Notifications V2.** 🎥 [Watch](https://youtu.be/jvZC3cdy5VM?feature=shared) our short tutorial

<Info>
  ### Note: v1 Notifications are not supported, to Enable Refund Keeper, you need to set up S2S Notifications v2
</Info>

3. **Fill out required App Store Data** 🎥 [Watch](https://youtu.be/jvZC3cdy5VM?feature=shared) our short tutorial

   1. Go to Project Settings and fill out these fields:

      1. App Store Connect Key Identifier
      2. App Store Connect Private Key
      3. App Store Connect Issuer Identifier

<iframe title="Enable Refund Keeper - tutorial" />

4. **Once you're set, you can choose Refund Handling Mode**

<img alt="" />

5. Click **Enable Refund Keeper** to activate the feature.

<img alt="" />

## Refund Preferences

*Apple allows developers to set a refund preference for each request, influencing the decision while Apple retains the final authority.*

| Option             | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| **Always Decline** | Maximizes revenue protection by contesting most refunds.               |
| **Always Refund**  | Automatically approves all refund requests.                            |
| **No Preference**  | A balanced approach that lets Apple decide based on the provided data. |

To adjust this setting, navigate to **Refund Preferences** in the Qonversion Dashboard and select your preferred option.

***

[Refund Keeper](refund-keeper)

[Analytics Overview](analytics-overview)


# Create Entitlements
Source: https://documentation.qonversion.io/docs/entitlements

Learn how to configure and control your app users' access with Qonversion Entitlements.

Entitlements represent an access level to the premium features of your application.

Examples of entitlements could be:‌

* YouTube Premium
* Netflix Standard, Netflix Premium
* Duolingo Plus

Most applications have only one entitlement that provides premium access.

## Create Entitlement

1. Navigate to the [Entitlements & Products configuration section](https://dash.qonversion.io/entitlements). Tap the Create Entitlement button.

<img alt="" />

2. Fill in the entitlement details:

<img alt="" />

* Name: short description that helps everyone in your team understand what features the entitlement unlocks.
* Entitlement ID: a unique ID to use on the SDK and API sides.
* Associated products: list of products that grant cross-platform entitlement.

***

[Subscription Management Mode](subscription-management-mode)

[Create Products](create-products)


# Events
Source: https://documentation.qonversion.io/docs/events-analytics

Visualize in-app user actions — trials, subscriptions, renewals, cancellations, and refunds — through the Qonversion Events Chart dashboard.

The Events Chart tab in Qonversion allows you to visualize and explore the data related to user actions and behaviours. It provides valuable insights into how users interact with your app, helping you identify patterns, trends, and opportunities for optimization.

You can find the Events Chart in the [Qonversion dashboard](https://dash.qonversion.io) under **Analytics → Events**. The chart supports custom date ranges, granularity (Day / Week / Month), and filtering by event, country, locale, OS version, app version, store, and more.

<img alt="" />

## Available Events

### Trials

* Trial Started
* Trial Converted
* Trial Canceled
* Trial Still Active
* Trial Billing Retry
* Trial Expired

### Subscriptions

* Subscription Started
* Subscription Renewed
* Subscription Canceled
* Subscription Billing Retry
* Subscription Upgraded
* Subscription Expired
* Subscription Downgraded
* Subscription Product Changed

### In-Apps

* In-App Purchase

### Refunds

* Subscription Refunded
* In-App Refunded

***

[Subscriptions](subscriptions)

[Cohorts](cohorts)


# Facebook Ads
Source: https://documentation.qonversion.io/docs/facebook

Send in-app subscription and purchases data to Facebook Analytics and Ads Manager

Measure what drives your revenue in Facebook Ads Manager and Facebook Analytics by tracking free-trial conversion to paid subscriptions, renewals, and even refunds. Qonversion sends data directly to your Facebook account to help you understand your marketing performance.

Use this integration to:

* See how your ads drive events like trial start, trial conversion, subscription renewals, and others.
* Measure the return on your advertising spend based on complete in-app revenue data.
* Create a custom Facebook audience (Lookalike Audience) based on your paying users to increase your advertising ROI (ROAS). Show ads to people similar to those who convert into paying users after a trial period.

<Info>
  ### Qonversion tracks revenue even if users don't open the app. This allows you to measure the performance of each subscription plan with 100% accuracy.
</Info>

## 1. Set up the SDKs

1. Make sure you have Facebook SDK installed. If you do not have Facebook integration yet, please use [this documentation](https://developers.facebook.com/docs/apis-and-sdks/).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Additionally, to attribute events sent from Qonversion, you need to set the same user ID at `_q_custom_user_id` key using the `Qonversion.shared().setProperty` method. Follow the [documentation](user-properties) to learn more about this method.

4. Set the same user ID by using Facebook SDK:

<CodeGroup>
  ```swift Swift theme={null}
  AppEvents.shared.userID = "yourSideUserID"
  ```

  ```objectivec Objective-C theme={null}
  [[FBSDKAppEvents shared] setUserID:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  AppEventsLogger.setUserID("yourSideUserID");
  ```

  ```kotlin Kotlin theme={null}
  AppEventsLogger.setUserID("yourSideUserID")
  ```
</CodeGroup>

5. Congratulations, you have completed the integration! From now on, Qonversion will share subscription events with Facebook with yourSideUserID attached.

<Warning>
  ### Do not track any purchase events on the client side

  Qonversion tracks all revenue events so if you track revenue events with Facebook SDK, you may double count the revenue in your Facebook account.
</Warning>

## 2. Configure the Facebook Integration

## Provide Integration Details

1. Get your Facebook **App Access Token**. You can use [this URL](https://developers.facebook.com/tools/explorer/) to access your token. Choose your Application in the top-right corner. Select the Get App Token and copy.

<Frame>
  <img />
</Frame>

2. Get **Facebook App ID** [here](https://developers.facebook.com/apps).

<img alt="" />

3. Navigate to the Integrations section in your Qonversion project, select [Facebook](https://dash.qonversion.io/app/integration/facebook), and provide the **App Access Token** and **App ID**.

## Configure the event names

You can use the default event names provided by Qonversion and corresponding to Facebook standard event names. If the standard Facebook event names are used, the events will show up in your Facebook Ads Account. If custom event names are used they will show up in Facebook Analytics, but they will not be delivered to Facebook Ads.

The main Qonversion events map to the following Facebook standard event names:

| Qonversion event name | Facebook Standard Event name |
| --------------------- | ---------------------------- |
| Trial Started         | StartTrial                   |
| Trial Converted       | Subscribe                    |
| Subscription Started  | Subscribe                    |
| Subscription Renewed  | Subscribe                    |
| In-App Purchase       | `fb_mobile_purchase`         |

<Warning>
  ### If you will use custom event names in Qonversion, then you can continue tracking the events with Facebook SDK as well.

  Please contact us, if you are not sure how to set up the tracking.
</Warning>

<Check>
  ### Done

  Now Qonversion will start sending subscription events to Facebook Ads Manager. You can view the detailed subscription-related events in your Facebook Ads account (Analytics, Ads Manager, Audience), get insights on your performance, and improve your marketing ROAS with Lookalike Audience.
</Check>

<Warning>
  ### It may take up to 24 hours for recently delivered events to appear in Facebook Analytics and Facebook Ads Manager.
</Warning>

***

[CleverTap](clevertap)

[Firebase](firebase)


# Fallbacks
Source: https://documentation.qonversion.io/docs/fallbacks

This ensures your No-Code screens remain available even when a network connection is lost or your app cannot reach Qonversion’s servers. Think of it as a backup plan that automatically loads a locally stored version of your screen when the live one can’t be fetched.

***

### Why Do You Need It?

Network conditions aren’t always reliable — especially for users who:

* Are in areas with weak or unstable connections
* Use restrictive networks or firewalls
* Experience short-term server or CDN outages

Without fallbacks, users might see **blank screens** or **failed paywall loads**. With fallbacks enabled, they’ll see a **locally stored** version of your paywall or onboarding screen instead — completely offline.

<Info>
  **In short:** Fallbacks make your screens fail-safe.
</Info>

***

## How It Works

When you publish a screen, Qonversion automatically allows you to generate a fallback file for it. This file contains all visual elements and logic needed to display the screen offline.

The system then behaves intelligently:

* **Smart Detection** – Automatically detects when a network or server error occurs.
* **Seamless Switch** – Instantly displays a locally cached fallback screen.
* **Fast Loading** – Fallback screens open from the device storage (no request delay).
* **Graceful Recovery** – When the connection returns, the SDK automatically switches back to online mode.

***

## What Triggers Fallback?

Fallbacks activate automatically when:

* **Network issues** — DNS failure, timeout, or unreachable endpoint.
* **Server errors** — HTTP 500-599 responses, rate limiting, or geoblocking.
* **Provider blocking** — Connection refused or socket exceptions.
* **CDN problems** — Gateway timeout or invalid cache.

You don’t need to handle these conditions manually — the SDK does it for you.

***

## Adding Fallback to Your Project

### Step 1 — Download Your Fallback File

1. Go to your **Dashboard** → **No-Codes** → **Screens**.
2. Select one or more published screens.
3. Click **Download Fallback File**.

<img alt="" />

This will generate a JSON file containing all published screens and their local data. The SDK looks for `nocodes_fallbacks.json` by default — keep the downloaded filename as-is unless you plan to set a custom name (see Custom Setup below).

<Warning>
  Keep in mind that whenever you release new screens or modify the existing ones, it’s essential to update your fallback file as well. Otherwise, it will still have outdated screens.
</Warning>

<Info>
  **Tip:** You can download fallbacks for all screens at once, or only for selected ones.
</Info>

***

### Step 2 — Add the File to Your Project

Once downloaded, you’ll integrate it into your app bundle so that the SDK can access it when offline.

✅ **Default Setup (No Code Required)**

Simply place the downloaded file in:

* `assets` folder for Android, or
* project root for iOS (same directory where Qonversion SDK is initialized).

When your app starts, the SDK will automatically detect and load the fallback file. No extra configuration is needed.

**Custom Setup (If You Need a Custom Path or Filename)**

<Warning>
  For iOS, you only need to specify the filename as the file will be automatically located within the app bundle. For Android, you should specify both the path and filename.
</Warning>

<Note>
  The custom-filename / custom-path API shown below is exposed natively on iOS (`NoCodesConfiguration.fallbackFileName`) and Android (`NoCodesConfig.Builder.setCustomFallbackFileName`). React Native and Flutter NoCodes config builders currently do **not** expose a fallback-filename setter — on those platforms keep the default name `nocodes_fallbacks.json` and place the file in the standard native location described above.
</Note>

You can specify the file path manually when initializing the SDK:

<CodeGroup>
  ```swift Swift theme={null}
  let configuration = NoCodesConfiguration(projectKey: "your-project-key", fallbackFileName: "my_custom_fallbacks.json")
  NoCodes.initialize(with: configuration)
  ```

  ```kotlin Kotlin theme={null}
  val config = NoCodesConfig.Builder(context, "your-project-key")
      .setCustomFallbackFileName("my_custom_fallbacks.json")
      .build()

  NoCodes.initialize(config)
  ```

  ```java Java theme={null}
  NoCodesConfig config = new NoCodesConfig.Builder(context, "your-project-key")
      .setCustomFallbackFileName("my_custom_fallbacks.json")
      .build();

  NoCodes.initialize(config);
  ```
</CodeGroup>

**Examples:**

**iOS**

* Custom name: `"my_offline_screens.json"`

**Android**

* Custom name: `"my_offline_screens.json"`
* File in subdirectory: `"assets/fallbacks/my_fallbacks.json"`
* Different path: `"assets/offline/my_screens.json"`

The system will automatically detect and use your fallback file, providing seamless offline experience for your users.

***

### ⚠️ Store Products Still Require Internet

While fallback screens load instantly, any screens that display App Store or Google Play products (subscriptions, one-time purchases, etc.) will still require an internet connection to fetch current pricing and availability information.

***

### ⚠️ Important Note About Android Asset Caching

When working with fallback files in your Android project, be aware that changes to asset files (including fallback JSON files) are cached by the build system. If you modify the fallback file's content, filename, or location, you must run a clean build to ensure the changes are properly included in your app. Without a clean build, the old cached version of the file may continue to be used, even if you've updated the source file.

***

## Summary

| **Feature**      | **Purpose**                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| **Fallbacks**    | Ensure No-Code screens remain available offline.                               |
| **How it works** | Detects network errors and loads locally cached screens.                       |
| **Setup time**   | \~5 minutes                                                                    |
| **Supported on** | iOS, Android, React Native, Flutter (RN/Flutter use the default filename only) |
| **Maintenance**  | Re-download after each screen update.                                          |

***

## Best Practices

* Always run `./gradlew clean` after modifying fallback files during development
* Test fallback functionality after any file changes

<Info>
  **💡 Fallbacks are your safety net.** Even if something breaks in the network or API layer, your users will still see a working screen — and your revenue stays protected.
</Info>

***

***

[Localization](ai-localization)

[Screens Preloading](screens-preloading)


# Feature List
Source: https://documentation.qonversion.io/docs/feature-list

Feature list templates for showcasing product benefits, plan comparisons, and value propositions. These components help users understand what they're getting before making a purchase decision.

All Feature List templates support:

* **Customizable icons** — checkmarks, custom icons, or emojis
* **Flexible layouts** — vertical lists, grids, and comparison tables
* **Full styling control** — colors, fonts, spacing

***

## Simple Lists

Single-line feature lists with icons — perfect for quick benefit overviews.

### Simple Checkmarks

A clean vertical list with checkmark icons for each feature.

<img alt="" />

**Features:**

* Green checkmark icons
* Single-line feature text
* Consistent vertical spacing
* Minimal, scannable design

**Use for:**

* Quick feature overviews
* "What's included" sections
* Benefit lists near CTAs

***

### Simple Icons

A feature list with customizable icons for each item.

<img alt="" />

**Features:**

* Custom icon per feature
* Single-line descriptions
* Icon color customization
* Visual variety

**Use for:**

* Feature categories with distinct icons
* Benefit lists with visual differentiation
* Branded feature presentations

***

## Two-Line Lists

Feature lists with title and description — for more detailed explanations.

### Two Lines Compact

Compact two-line layout with title and supporting description.

<img alt="" />

**Features:**

* Bold feature title
* Smaller description text
* Icon on the left
* Tight spacing for mobile

**Use for:**

* Detailed feature explanations
* Benefit breakdowns
* Value proposition lists

***

### Two Lines Emoji

Two-line features with emoji icons instead of traditional icons.

<img alt="" />

**Features:**

* Emoji as visual markers
* Title + description format
* Friendly, approachable style
* Easy customization

**Use for:**

* Casual or playful apps
* Quick visual recognition
* Cross-platform consistency

***

### Two Lines Dividers

Two-line features separated by visual dividers.

<img alt="" />

**Features:**

* Horizontal dividers between items
* Clear visual separation
* Title + description format
* Structured appearance

**Use for:**

* Formal feature lists
* Terms or policy sections
* Detailed benefit breakdowns

***

## Comparison Tables

### Free vs Pro

A side-by-side comparison showing free and premium plan features.

<img alt="" />

**Features:**

* Two-column layout (Free | Pro)
* Checkmarks for included features
* X marks for excluded features
* Clear plan differentiation

**Use for:**

* Subscription upgrade screens
* Plan comparison paywalls
* Feature gating visualization

***

## Feature Grids

Two-column grid layouts for compact feature displays.

### Feature Grid Icons

A 2-column grid with icon and text for each feature.

<img alt="" />

**Features:**

* 2-column responsive grid
* Icon above text
* Centered alignment
* Balanced visual weight

**Use for:**

* App capability showcases
* Compact feature sections
* Visual feature highlights

***

### Feature Grid Text

A 2-column grid with text-only feature cards.

<img alt="" />

**Features:**

* Text-based feature cards
* Title + description format
* Clean, minimal design
* No icons required

**Use for:**

* Text-heavy feature lists
* Detailed explanations
* Professional presentations

***

## Customization

After adding a Feature List template, you can customize:

**Content:**

* Feature titles and descriptions
* Icon selection (from Tabler icon library)
* Emoji choices
* Number of features displayed

**Styling:**

* Icon colors and sizes
* Typography (font, size, weight)
* Spacing and alignment
* Background colors
* Divider styles

***

## Best Practices

* **Keep it scannable** — 3-5 features is optimal for mobile
* **Lead with value** — put your strongest benefits first
* **Use consistent icons** — stick to one icon style throughout
* **Match your brand** — use brand colors for icons and accents
* **Be specific** — "Unlimited exports" beats "More features"
* **Highlight differences** — in comparisons, emphasize what's exclusive to premium
* **Test readability** — ensure text is legible on all device sizes

***

***

[CTA Buttons](cta-buttons)

[Awards](awards)


# Stop experiments
Source: https://documentation.qonversion.io/docs/finish-experiment

Roll your experiment out once you accepted or rejected the hypothesis

Once the statistical significance is reached, you can end the experiment using the **End** button. Once you click on it, Qonversion:

* Stops returning variant-related payload to your app.
* Stops attributing events generated by exposed users to the experiment.
* Releases all assigned users at once — on their next config request they are evaluated fresh against the remaining active remote configs and experiments for that context key. This is the only experiment change that re-evaluates existing users.

<img alt="" />

***

What’s Next

* [Splitting rules](splitting-rules)


# Firebase
Source: https://documentation.qonversion.io/docs/firebase

Send Qonversion revenue events including purchases, trial conversions, subscription renewals, and refunds to Firebase for user behavior tracking.

Qonversion can send [revenue events](integrations-overview#tracked-events), including purchases, trial conversions, subscription renewals, and even refunds, to your Firebase account. This allows you to match your users' behaviour with their payment history in Firebase and empower your product decisions.

## 1. Setup the SDKs

1. Make sure you have Firebase SDK installed. Check the official Firebase SDK documentation [here](https://firebase.google.com/docs/analytics/get-started)
2. Set Qonversion SDK following [Installing the SDKs](install-sdk) guides.
3. Send *firebaseAppInstanceId* to Qonversion via [User Properties](user-properties)

<CodeGroup>
  ```swift Swift theme={null}
  if let appInstanceID = Analytics.appInstanceID() {
      Qonversion.shared().setUserProperty(.firebaseAppInstanceId, value: appInstanceID)
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyFirebaseAppInstanceId value:[FIRAnalytics appInstanceID]];
  ```

  ```java Java theme={null}
  FirebaseAnalytics.getInstance(context).getAppInstanceId().addOnCompleteListener(task -> {
      final String appInstanceId = task.getResult();
      if (appInstanceId != null) {
        Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.FirebaseAppInstanceId, appInstanceId);
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  FirebaseAnalytics.getInstance(requireContext()).appInstanceId.addOnCompleteListener { task ->
      task.result?.let { appInstanceId ->
          Qonversion.shared.setUserProperty(QUserPropertyKey.FirebaseAppInstanceId, appInstanceId)
      }
  }
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.firebaseAppInstanceId, appInstanceId);
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.FIREBASE_APP_INSTANCE_ID, appInstanceId);
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.FirebaseAppInstanceId, appInstanceId);
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.FIREBASE_APP_INSTANCE_ID, appInstanceId);
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.FIREBASE_APP_INSTANCE_ID, appInstanceId);
  ```
</CodeGroup>

<Warning>
  Measurement `app_instance_id` is expected to be a 32-digit hexadecimal number.

  Example of `app_instance_id `B18FE2FF75795C219BCD30B58377C5ED
</Warning>

## 2. Configure the Firebase Integration

1. Copy your Firebase App ID and Measurement Protocol API secret from the [Google Analytics Console](https://analytics.google.com/analytics): *Admin → Data Streams → Select existing or create a new stream for your App*

<Frame>
  <img />
</Frame>

2. Open the **Integrations** section in your [Qonversion account](https://dash.qonversion.io/integrations).
3. Click **+ Add new**, select **Firebase**, and choose the target store (iOS or Android) for the integration.
4. Provide the **API Secret** and **App ID** copied in the first step in the corresponding fields, then save.

<Frame>
  <img />
</Frame>

## 3. Pay attention to event names

Event names:

* Must be 40 characters or fewer
* May only contain alpha-numeric characters and underscores
* Must start with an alphabetic character.

Names

* Use [Google default event names](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#purchase) for revenue metrics to be computed accurately. Examples: *purchase* and *refund*.
* Avoid using [Google reserved event names](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=firebase#reserved_names): *in\_app\_purchase*, *notification\_receive*, *user\_engagement*, etc.
* Other event names can be customised.

<Check>
  ### Done

  Qonversion will send In-App purchases and subscription events to your Firebase account. You can make changes to event names and other setting on the Firebase integration settings page in Qonversion.
</Check>

## Event Payload

Qonversion delivers each tracked event to the Firebase Measurement Protocol with the shape below. `value`, `currency`, and `storefront` are conditional (only present when the underlying revenue/transaction record carries them); `app_instance_id` and `transaction_id` are always populated.

When user properties have been recorded for the user, an additional `user_properties` object is included alongside `events`. Each entry is filtered through Firebase's restrictions: keys must be 1-24 characters, start with a letter, contain only `[a-zA-Z0-9_]`, and not begin with the reserved `firebase_`, `google_`, or `ga_` prefixes; values must be at most 36 characters. Entries that fail any of these checks are silently dropped from the payload.

<CodeGroup>
  ```json theme={null}
  {
     "app_instance_id":"B18FE2FF75795C219BCD30B58377C5ED",
     "user_id":"QON_...",
     "timestamp_micros":"1700000000000000",
     "events":[
        {
           "name":"event_name",
           "params":{
              "transaction_id":"500000601234560",
              "items":[
                 {
                    "item_id":"product_id"
                 }
              ],
              "value":7.7,
              "currency":"CHF",
              "storefront":"USA"
           }
        }
     ]
  }
  ```
</CodeGroup>

***

[Facebook Ads](facebook)

[Google Ads](google-ads)


# Flutter 5.+ migration guide
Source: https://documentation.qonversion.io/docs/flutter-5-migration-guide

Historical migration guide for upgrading the Qonversion Flutter SDK to major version 5.+: updated initialization, renamed methods, and revised purchase and entitlement APIs.

## Upgrading version

Increase the dependency version in your *pubspec.yaml* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```yaml theme={null}
  dependencies:
    qonversion_flutter: ^5.0.0
  ```
</CodeGroup>

## Initialization

Qonversion Flutter SDK 5 contains significant changes in how the library is initialized. We are moving from a static class approach to an instance-based one. Before, you initialized Qonversion using the `launch` call:

<CodeGroup>
  ```dart Flutter theme={null}
  Qonversion.launch('projectKey', isObserveMode: true);
  ```
</CodeGroup>

Now, instead, you should create a `QonversionConfig` object using `QonversionConfigBuilder` and provide it to the initialization method as follows:

<CodeGroup>
  ```dart Flutter theme={null}
  final config = new QonversionConfigBuilder(
    'projectKey',
    QLaunchMode.subscriptionManagement
  ).build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

Note that instead of providing the `observeMode` flag to the `launch` call, you should provide a concrete value from the `QLaunchMode` enum, depending on which mode you use Qonversion. Also, we've renamed our modes to make them more transparent for users:

* "Observe" mode becomes "Analytics" mode,
* "Infrastructure" mode becomes "Subscription Management" mode.

After the initialization, you can access the Qonversion instance whenever you want as follows:

<CodeGroup>
  ```dart Flutter theme={null}
  Qonversion.getSharedInstance();
  ```
</CodeGroup>

So you should replace all your Qonversion calls with the construction above.

Also, if you were using `Qonversion.setDebugMode()` for testing purposes, you should now call the `setEnvironment(QEnvironment.sandbox)` method of the `QonversionConfigBuilder`.

As no `launch` method is available anymore, you won't get `QLaunchResult` as a result. The good news is that there are analogues for all the fields you might have been using from there:

* for `uid`, call `userInfo()` and get the `QUser.qonversionId` from the result,
* for `products` call `products()`,
* for `offerings` call `offerings()`,
* for `permissions`, call `checkEntitlements()`.

## Entitlements

We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

| Version \<4               | Version 4+                 |
| ------------------------- | -------------------------- |
| QPermission               | QEntitlement               |
| QProductRenewState        | QEntitlementRenewState     |
| QPermissionSource         | QEntitlementSource         |
| QPermissionsCacheLifetime | QEntitlementsCacheLifetime |
| checkPermissions          | checkEntitlements          |
| updatedPurchasesStream    | updatedEntitlementsStream  |

The `QEntitlement` class contains the same information as the `QPermission` with a renaming of the `permissionId` field - now it's named simply `id`.

* There is no `setPermissionsCacheLifetime` method in Qonversion. You should provide `QEntitlementsCacheLifetime` to `QonversionConfigBuilder` during the initialization using the `setEntitlementsCacheLifetime` method.

<CodeGroup>
  ```dart Flutter theme={null}
  final config = new QonversionConfigBuilder(
      'projectKey',
      QLaunchMode.subscriptionManagement
  )
      .setEntitlementsCacheLifetime(QEntitlementsCacheLifetime.year)
      .build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

## Automation changes

We've also changed the way the `Automations` is used. As in Qonversion, you should use `Automations` via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.

<Info>
  ### You should access the shared instance of `Automations` strictly after you initialize Qonversion, else an exception will be thrown.
</Info>

<CodeGroup>
  ```dart Flutter theme={null}
  final config = new QonversionConfigBuilder(
      'projectKey',
      QLaunchMode.subscriptionManagement
  ).build();
  Qonversion.initialize(config);
  Automations.getSharedInstance().setDelegate(...);
  ```
</CodeGroup>

Also, the methods for working with push notifications were moved from `Qonversion` to `Automations`, so if you were using the following methods:

* `setNotificationsToken`,
* `handleNotification`,
* `getNotificationCustomPayload`, make sure to make calls from the Automations instance instead of the Qonversion one.

## Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

* all the internal classes were moved to the `internal` package, and DTO classes were moved to the `dto` package to make the library file structure more readable;
* the deprecated methods `resetUser` and `setUserId` were removed. `resetUser` was deprecated for a long time, and it did nothing, so there is nothing to replace this call with, remove the call if you were still using it for some reason. `setUserId` should be replaced with the `setProperty` call with `QUserProperties.customUserId` parameter;
* added the new method `userInfo`, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
* added new enum values - `QOfferingTag.Unknown` and `QTrialDuration.Unknown`, which are used when parsing fails;
* `facebookAttribution` and `advertisingId` values were added to the `QUserProperty` enum;
* native modules' error codes were refactored - now clear textual error codes are provided.
* the following methods and classes renaming took place:

| Old name                              | New name                           |
| ------------------------------------- | ---------------------------------- |
| `addAttributionData`                  | `attribution`                      |
| `setAdvertisingID`                    | `collectAdvertisingId`             |
| `setAppleSearchAdsAttributionEnabled` | `collectAppleSearchAdsAttribution` |
| `ProrationMode`                       | `QProrationMode`                   |

***

[Android 4.+ migration guide](android-4-migration-guide)

[React Native 4.+ migration guide](react-native-4-migration-guide)


# Flutter 7.+ migration guide
Source: https://documentation.qonversion.io/docs/flutter-7-migration-guide

Historical migration guide for upgrading the Qonversion Flutter SDK to major version 7.+: renamed entities and methods with a before/after reference for updating your integration.

## Upgrading version

Increase the dependency version in your *pubspec.yaml* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```yaml theme={null}
  dependencies:
    qonversion_flutter: ^7.0.0
  ```
</CodeGroup>

## Renamings

In this major version, we have renamed several entities and public methods to make our namings more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade    | After upgrade           |
| ----------------- | ----------------------- |
| `QUserProperty`   | `QUserPropertyKey`      |
| `setUserProperty` | `setCustomUserProperty` |
| `setProperty`     | `setUserProperty`       |

## User properties changes

As mentioned above, we have renamed the`QUserProperty` enum to `QUserPropertyKey`. It was made to release the name `QUserProperty` for a class, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```dart Flutter theme={null}
  try {
    QUserProperties userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach((userProperty) {
      print('User property - key: ' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

`QUserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                  | Description                                                                                              |
| -------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `getProperty`        | `key` - string             | Searches for a property with the given property `key` in all properties list                             |
| `getDefinedProperty` | `key` - `QUserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `QUserPropertyKey` enum with a `custom` key to represent all the custom properties.

***

[Android 6.+ migration guide](android-6-migration-guide)

[React Native 6.+ migration guide](react-native-6-migration-guide)


# Flutter SDK 7.x to 8.x migration guide
Source: https://documentation.qonversion.io/docs/flutter-8-migration-guide

We've upgraded the Google Play Billing Library dependency on Android to version 6 in this release, which has led to major changes in the product and subscription management parts of our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *pubspec.yaml* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```yaml theme={null}
  dependencies:
    qonversion_flutter: ^8.0.0
  ```
</CodeGroup>

## Product updates

### Qonversion and Google Play product link changes

Google Play has recently upgraded the structure of their subscription products. We've written about it [in our blog](https://qonversion.io/blog/google-play-billing-library-5-0/). In short, they combined the same subscriptions with different durations into a single subscription with different base plans. In addition, they announced different kinds of offers to base plans, including free trials or introductory prices. In this release, we begin to support those changes.

Previously Qonversion **subscription** products required a Google Play subscription identifier. Now you can also set a specific **base plan** for the subscription. Different base plans of the same subscription can be linked to different Qonversion products. Let's have a look at an example.

Let's say you sell monthly and annual subscriptions in your app, both on Android and iOS. With the previous Qonversion SDK versions, you would specify two Qonversion products (`premium_monthly` and `premium_annual`), two App Store products (`premium_monthly_ios` and `premium_annual_ios`), and two Google Play products (`premium_monthly_android` and `premium_annual_android`). Then you would link those store products to Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_monthly_android`,

`premium_annual` - `premium_annual_ios` and `premium_annual_android`.

With the new Google Play Subscriptions structure, you can create only one subscription for Android - `premium_android` and two base plans for it (`monthly` and `annual`). With this done, you can now use a single subscription for both Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_android` with `monthly` base plan,

`premium_annual` - `premium_annual_ios` and `premium_android` with `annual` base plan.

### Store details for the `QProduct` class

Speaking of the SDK side - the first big part of the changes is the addition of the new `basePlanId` field to `QProduct` which can be set to the product via Qonversion Dashboard.

We have deprecated the `QProduct.skuDetails` field, because `SkuDetails` contain information only for backward compatible base plans and are now deprecated in the Google Play Billing Library. Instead, we have added the new `storeDetails` field of type `QProductStoreDetails`, which contains all the store information for the Google Play Product. You can find the specifications of that class [on this page](google-play-product-details).

If `basePlanId` is not specified for a product, it means one of the following:

* it is a one-time (in-app) product that can not have any base plans,
* it is a product that was not updated in the Qonversion dashboard after this version was released,
* it is an iOS-only product.

In the case of the in-app product, both `skuDetails` and `storeDetails` fields will contain information about that in-app. But in the second case, when there is a subscription product without a specified base plan, the `skuDetails` field will contain information about the **backward compatible** base plan, while the `storeDetails` field will only contain common subscription information without base-plan-specific data. It means that you should start using `storeDetails` field for base-plan-specific data (like price, duration, and so on) for Android subscription products only if you've specified their base plan IDs in Qonversion product settings.

### The other `QProduct` fields changes

Along with the above changes, we have changed the `type` field and removed the `duration` and `trialDuration` fields from the product class. The `type` and `duration` were previously being set via the dashboard, and the `trialDuration` was calculated from the store details and was represented as an enumeration with several common durations. Now, the product `type` is calculated from the store details both for Android and iOS. We've also added the `intro` value to `QProductType` to separate `trial` and `intro` products (Android only for now). An `unknown` value was also added for the cases where we are unable to determine the product type. The `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod`. Both properties are of type `QSubscriptionPeriod` and the values are also calculated from the store details for both platforms.

The last thing to note is that we've also changed the `prettyPrice` and `prettyIntrodactoryPrice` fields calculation for Android. Earlier they were calculated from `skuDetails`, while now we first try to use `storeDetails` if possible and only then fall back to `skuDetails`.

### `QProduct` updates summary

Below is the shortened summary of the `QProduct` changes:

* new `basePlanId` field, specifying concrete subscription base plan for Google Play subscriptions, added,
* `skuDetails` field deprecated,
* new `storeDetails` field, containing information about Google Play product, added;
* the `type` field is now calculated based on store details both for Android and iOS, instead of the value set via the Qonversion dashboard. The `intro` and `unknown` values were added to `QProductType` to separate cases of trial and intro products (Android only for now) and also the case when we are unable to determine the product type;
* the `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod` fields of type `QSubscriptionPeriod` with the values calculated from the store details both for Android and iOS;
* the `prettyIntroductoryPrice` field on Android now prefers `storeDetails` to get the price from, and only then - `skuDetails`.

## Purchase flow updates

In this release, we have changed the `purchase` and `updatePurchase` methods signatures. Previously there were several methods for different sets of arguments. Now we've arranged all those properties into classes - `QPurchaseModel` and `QPurchaseUpdateModel`, that should be instantiated and provided to the single `purchase` or `updatePurchase` method.

You can create instances of those classes either manually or by using the utility functions `toPurchaseModel` and `toPurchaseUpdateModel` added to the `QProduct` class.

Below is an example of how the `purchase` flow has changed:

<CodeGroup>
  ```dart Flutter theme={null}
  // Old
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().purchaseProduct(product);

  // New
  final QPurchaseModel purchaseModel = product.toPurchaseModel();
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().purchase(purchaseModel);
  ```
</CodeGroup>

And an `updatePurchase` flow example:

<CodeGroup>
  ```dart Flutter theme={null}
  // Old
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().updatePurchaseWithProduct(
    newProduct: product,
    oldProductId: 'oldProductId',
  );

  // New
  final QPurchaseUpdateModel purchaseUpdateModel = product.toPurchaseUpdateModel('oldProductId');
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

If you were using only product identifiers, you can create purchase models manually as follows:

<CodeGroup>
  ```dart Flutter theme={null}
  // Old
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().purchase('productId');

  // New
  final QPurchaseModel purchaseModel = new QPurchaseModel('productId');
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().purchase(purchaseModel);
  ```
</CodeGroup>

<CodeGroup>
  ```dart Flutter theme={null}
  // Old
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().updatePurchase(
    newProductId: 'newId',
    oldProductId: 'oldId',
  );

  // New
  final QPurchaseUpdateModel purchaseUpdateModel = new QPurchaseUpdateModel('newProductId', 'oldProductId');
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

If necessary, you can provide a specific offer for subscription purchase.

<CodeGroup>
  ```dart Flutter theme={null}
  // Specifying offer via the `toPurchaseModel` method:
  final QProductOfferDetails productOfferDetails = ...; // Choose an offer from `storeDetails`
  final QPurchaseModel purchaseModel = product.toPurchaseModelWithOffer(productOfferDetails);

  // Specifying offer ID via the `toPurchaseModel` method:
  final QPurchaseModel purchaseModel = product.toPurchaseModel('offer_id');

  // Specifying offer ID via the constructor:
  final QPurchaseModel purchaseModel = new QPurchaseModel('productId', 'offer_id');
  final QPurchaseUpdateModel purchaseUpdateModel = new QPurchaseUpdateModel('newProductId', 'oldProductId', 'offer_id');

  // Specifying offer ID after the purchase model creation:
  purchaseModel.offerId = 'offer_id';
  ```
</CodeGroup>

If provided, we will try to find and purchase the offer with the specified ID for the requested Qonversion product. If there is no offer with the specified ID, an error will be returned. If no offer ID is provided for the subscription purchase of Qonversion product with a specified base plan ID, then we will choose the most profitable offer for the client from all the available offers. We calculate the cheapest price for the client by comparing all the trial or intro phases and the base plan. For iOS, old Qonversion products (where the base plan ID is not specified), or in-app products, the offer ID is ignored.

You can also remove any intro/trial offer from the purchase (use only a bare base plan). For that purpose, you should call `removeOffer` method of purchase model:

<CodeGroup>
  ```dart Flutter theme={null}
  purchaseModel.removeOffer()
  ```
</CodeGroup>

## The other changes

* Gradle on Android was upgraded to the version 8;
* The `checkTrialIntroEligibility` method improved and now detects the eligibility based on store details on Android;
* The `QProductDuration` and `QTrialDuration` classes were removed;
* The `QProrationMode` enum was removed and replaced with `QPurchaseUpdatePolicy` ([read more](making-purchases)).

***

[Android SDK 6.x to 7.x migration guide](android-7-migration-guide)

[React Native SDK 6.x to 7.x migration guide](react-native-7-migration-guide)


# Flutter SDK 8.x to 9.x migration guide
Source: https://documentation.qonversion.io/docs/flutter-9-migration-guide

We've upgraded the Google Play Billing Library dependency for Android to version 7 in this release, leading to several changes in our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *pubspec.yaml* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```yaml pubspec.yaml theme={null}
  dependencies:
    qonversion_flutter: ^9.0.0
  ```
</CodeGroup>

## Android deployment upgrades

With the new Google Play Billing Library 7 we've increased our `minSdkVersion` to 21 and `targetSdkVersion` to 34 for Android.

If you were using lower `minSdkVersion` you should upgrade it to 21 to use the latest version of our SDK and Google Play Billing Library. If you have already targeted the 21+ version, you should do nothing.

## Installment plans support

In the latest library version, Google introduces installment plans, when a customer commits to pay for several subsequent subscription periods. In our release, we've added a new field `installmentPlanDetails` to `QProductOfferDetails` with the details of the installment plan if they exist. It contains the following information:

| Field                               | Type | Description                                                               |
| ----------------------------------- | ---- | ------------------------------------------------------------------------- |
| `commitmentPaymentsCount`           | int  | Committed payments count after a user signs up for this subscription plan |
| `subsequentCommitmentPaymentsCount` | int  | Subsequent committed payments count after this subscription plan renews   |

We've also added an `isInstallment` flag to `QProductStoreDetails` to check if the current product has an installment plan or not.

Below is an example of those fields usage:

<CodeGroup>
  ```dart Flutter theme={null}
  var products = await Qonversion.getSharedInstance().products();
  var installmentProduct = products["installmentProductId"];
  var storeDetails = installmentProduct?.storeDetails;
  if (storeDetails?.isInstallment == true) {
    var installmentPlanDetails = storeDetails?.basePlanSubscriptionOfferDetails?.installmentPlanDetails;
    // Use the installment plan information
  }
  ```
</CodeGroup>

## Fallback files

We're happy to introduce the fallback files support in this release to make our system reliability even higher. Fallback files allow your app to work as expected in rare cases of network connection or Qonversion API issues for new users without a cache available. This allows purchases and entitlements to be processed for new users even if the Qonversion API faces issues. This also makes it possible to receive remote configs for cases when the network connection is unavailable.

Fallback files are available both on iOS and Android.

Read more about the fallback files in [the documentation](system-reliability#fallback-files).

## Error codes

In this release, we have added the `QErrorCode` enum with the list of defined Qonversion error codes. Now you can compare any error code with the defined one to check any specific case as follows:

<CodeGroup>
  ```dart Flutter theme={null}
  try {
    await Qonversion.getSharedInstance().purchase(purchaseModel);
  } on QPurchaseException catch (e) {
    if (e.code == 'StoreProductNotAvailable') {
      // The requested product is unavailable for purchase.
    }
  }
  ```
</CodeGroup>

We've also changed the type of `QError.code` field from `String` to `QErrorCode`. `QPurchaseException.code` continues to be a `String` matching the `QErrorCode` enum value (e.g. `'StoreProductNotAvailable'`).

## The other changes

* Pending purchases support was added for prepaid subscriptions on Android.
* `QEligibilityStatus` `nonIntroProduct` was renamed to `nonIntroOrTrialProduct` to better reflect the meaning.

***

[Android SDK 7.x to 8.x migration guide](android-8-migration-guide)

[React Native SDK 7.x to 8.x migration guide](react-native-8-migration-guide)


# Flutter
Source: https://documentation.qonversion.io/docs/flutter-sdk

Install Qonversion Flutter SDK to validate user receipts, and get in-app subscription analytics and third-party integrations.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/flutter-sdk?label=Latest%20Release)](https://github.com/qonversion/flutter-sdk/releases)

## Installation

To use Qonversion in your Flutter app, add qonversion [as a dependency in your pubspec.yaml file](https://flutter.io/platform-plugins/):

<CodeGroup>
  ```yaml pubspec.yaml theme={null}
  dependencies:
    qonversion_flutter: ^11.0.0
  ```
</CodeGroup>

Then install dependency

<CodeGroup>
  ```bash Terminal theme={null}
  flutter pub get
  ```
</CodeGroup>

## Kids Mode for Qonversion Flutter SDK

In case you are building an App for Kids, [follow this guide](kids-mode-sdk) to learn about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# Creating Screens
Source: https://documentation.qonversion.io/docs/getting-started

Once your store connection and SDK setup are complete, you can start designing your first screen inside the Builder. Each screen is made of modular components that you can arrange, style, and connect to your products — visually, with no code.

Once your SDK is [installed](installation) and initialized, you can start building your first in-app screen directly from the Qonversion dashboard.

No builds. No releases. Everything happens visually — right inside your browser.

***

## Accessing the Builder in Dashboard

1. Open your project in the Qonversion **Dashboard**.
2. Navigate to the **No-Code Builder** section in the left sidebar.
3. Click **Create New Screen** to begin.

You’ll first choose what type of screen you want to create:

* **Mobile Paywall** – single-page layout for offers or subscriptions.
* **Mobile Onboarding** – multi-page layout for tutorials or funnels.

Once selected, you can start from a **template** or design from **scratch**.

<img alt="" />

***

## Overview of the Interface

The Builder interface is designed to feel familiar to both designers and developers — a simple layout with real-time preview and drag-and-drop control.

### Canvas & Settings

The main working area where your screen layout lives. You can add, move, and resize components directly on the canvas and see updates instantly.

<img alt="" />

The Canvas is your adaptive artboard — where your entire screen layout lives.

<Warning>
  Before adding components, it’s important to configure your **Canvas Settings,** as these define how your design behaves and looks across devices.

  * Set your Default Product (if applicable).
  * Choose your Font Family and Layout Direction.
  * Enable Safe Area to automatically apply 20 px horizontal and 59 / 34 px vertical padding.
</Warning>

You can access **Canvas Settings** from the **Right Panel** when **Canvas Layer** is Selected.

**Canvas settings** act as the foundation of your design. They define global appearance and structure before you start adding components.

***

#### Screen & Safe Area

<Info>
  Tip: Keep “**Apply Safe Area**” enabled to prevent overlapping with system UI elements
</Info>

| Setting             | Description                                                                                                                                                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show Safe Area**  | Toggles visible device margins on or off to help align elements.                                                                                                                                                                        |
| **Apply Safe Area** | Automatically applies platform-specific insets to keep your content within safe boundaries (e.g., notch, home indicator). When enabled, it adds: • 20 px horizontal padding (left and right) • 59 px top padding • 34 px bottom padding |

<img alt="" />

***

#### Default Product

If your screen includes purchase options, set a **Default Product** here. This determines which product is **pre-selected when the screen loads** — for example, your most popular subscription plan.

| Setting             | Description                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| **Default Product** | Select one of your existing products to pre-select on screen load                                      |
| **Add Products**    | Opens the product linking modal where you can connect or create new products directly from the Builder |

<img alt="" />

***

#### Typography

Choose a global Font Family to apply across all text components on the screen. Individual components can override this setting later.

| Setting         | Description                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| **Font Family** | Defines the base typeface used by all text elements. Supports 20 + system and web-safe fonts. |

***

#### Layout

Controls how elements are positioned and spaced within the screen. This setting determines stacking direction, alignment, and gaps between child components.

| Setting          | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Direction**    | Defines the layout flow — **Vertical (↓)** for stacked components or **Horizontal (→)** for side-by-side layouts. |
| **Distribution** | Sets how elements align within the available space (Start, Center, End, or Space Between).                        |
| **Gap**          | Controls equal spacing between immediate child components.                                                        |

<Info>
  For most paywalls, use **Vertical** Direction → **Space Between** Distribution. **Space Between** Setting disables **Gap** Setting
</Info>

***

#### Spacing

Fine-tune how your Canvas interacts with the overall screen space.

| Setting     | Description                                                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Margin**  | Adds space outside your Canvas (rarely used).                                                                                                             |
| **Padding** | Adds internal space within your Canvas. When **Safe Area** is applied, padding values default to **Top 59 px**, **Bottom 34 px**, **Left / Right 20 px**. |

These values ensure that essential content is always visible on all modern device screens.

***

#### Background

Apply a base background to your screen — solid color, gradient, or image.

| Setting            | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| **Add Background** | Opens the background picker for color, gradient, or image upload. |

<Info>
  Use solid backgrounds for paywalls, or gradients/images for onboarding and promotional flows.
</Info>

### Left Sidebar

The **Left Sidebar** is your main navigation panel inside the Builder. It helps you manage your project’s structure, screens, and all components.

It includes three tabs: **Pages**, **Layers**, and **Assets**.

<Frame>
  <img />
</Frame>

***

#### Pages

Manage and organize your app screens within a project.

* Create and manage multiple pages within the same screen set (e.g., paywall + thank-you page).
* Click **+ Add Page** to create a new one.
* Reorder or rename pages at any time.
* The currently active page is highlighted (e.g., **Start Page**).

This is where you’ll switch between **single-page** and **multi-page** screens when building onboarding flows.

***

#### Layers

View and organize all elements currently on your selected page.

* Manage the **hierarchy and nesting** of containers and components.
* Lock or hide specific layers for easier editing.
* Reorder components with drag-and-drop.

Layers reflect your current **Canvas** structure in real time.

***

#### Assets

Access and add ready-to-use components and elements.

**Elements**:

* **Basic** – headings, text, buttons, containers
* **Interactive** – toggles, sliders, tabs
* **Media** – images, GIFs, Lottie files, (video coming soon)
* **Structure** and **Sections** – pre-built headers, footers, and layout blocks

**Components:**

* **Product Blocks** – pre-filled elements linked to your Qonversion products

You can also use the **search bar** to quickly find a component or element type.

***

#### Right Sidebar (Properties)

Shows detailed settings for the selected component.

Here you can customize:

* Layout and positioning
* Icons, Actions, Content and Variables
* Typography and colors
* Borders, shadows, and backgrounds
* Visibility and behavior

and more.

<Frame>
  <img />
</Frame>

***

#### Flow Bar

The Flow Bar gives you quick access to the most commonly used tools and preview controls. It includes:

* A set of frequently used components for faster editing
* Zoom controls to adjust your view of the Canvas
* A device selector to preview your layout on iOS, Android, and tablet screens

Use it to fine-tune your design across devices and ensure responsive layout behavior.

<Frame>
  <img />
</Frame>

***

## Publishing & Versioning

Before publishing your screen, you’ll need to assign a **Context Key** — a unique identifier that links the screen you build in Qonversion to your app through the SDK.

* Click **Settings** in the top bar and enter a descriptive name (for example, *main\_paywall* or *onboarding\_flow*).
* Once the key is set, click **Publish** in the top-right corner.

Publishing makes your screen available to be called via SDK — no app update or store release required. However, the screen will only appear in your app after you call its **Context Key** from your code.

<img alt="" />

***

[Product Setup & Store Connection](product-setup-store-connection-1)

[Components](components)


# Migrating from Glassfy
Source: https://documentation.qonversion.io/docs/glassfy-migration-guide

Step-by-step guide to migrate your in-app subscription infrastructure from Glassfy to Qonversion — store configuration, products and entitlements, Remote Configs, SDK setup, and user-base migration.

Glassfy has [announced](https://glassfy.io/blog/important-update-glassfy-services-ending-december-2024/) that they will be ceasing operations in December 2024, and we're here to support the users during the transition. Enjoy[ 6 months of the Qonversion](https://qonversion.io/glassfy-alternative) completely for free, allowing you plenty of time to get comfortable with all that Qonversion has to offer.

<img alt="" />

To ensure a smooth transition, we have prepared a migration guide to help you move seamlessly from Glassfy to Qonversion.

First and foremost, [register](https://go.qonversion.io/zyUM) at Qonversion.

The registration will take you through an onboarding where you'll have to fill out information about your project, insert links - all to help you add your project to Qonversion. We highly recommend following this flow and not skipping any settings during registration. Anyway, we'll also cover the scenario if you don't fill these out.

## Store Configuration

<br />

### Connecting App Store

Here's what you had in Glassfy:

<img alt="" />

To configure App store in Qonversion, you will need the following fields:

1. **App-Specific Shared Secret**: Simply copy this value from the Apple Shared Secret field in the App Store Configuration section in Glassfy. Check the screenshot above. Alternatively, [here's](/docs/ios-app-store-info-fields#2-generate-the-app-specific-shared-secret) a more detailed guide on how to obtain this.
2. **App Store ID**: You'll find your App Store ID in the URL of your App Store Connect account. For example, if your URL is something like [https://apps.apple.com/us/app/example-app/id123456789](https://apps.apple.com/us/app/example-app/id123456789), then 123456789 is your app’s Apple ID.

### Connecting Google Play Console

Here's what you saw at Glassfy:

<img alt="" />

To set up your Google Play account in Qonversion, you will need the following:

1. **Android Package Name**: This is usually the applicationID in your app-level build.gradle file. You can either copy it from there or simply copy the **Android Package Name** field in your settings from Glassfy.
2. **Service Account Credentials JSON**: Copy the value from the **Google JSON Key** in the screenshot above or simply attach the same file you used in Glassfy. [Here's more](/docs/android-store-setup) on how you can get Google Play Service Account Key.

> 🚧 Can't find the fields?
>
> If you skipped filling in these details during the onboarding, navigate to the **Settings** -> **Stores**  on your Qonversion dashboard and fill out the empty fields.

## Products, Entitlements, and Remote Configs

Once all the data is filled in and the stores are set up, it's time to configure Products, Entitlements, and Remote Configs.

Here's how we refer to the same things differently:

| Glassfy     | Qonversion     |
| :---------- | :------------- |
| Permissions | Entitlements   |
| SKUs        | Products       |
| Offerings   | Remote Configs |

### Entitlements (Permissions)

Let's start with Entitlements. Similar to how you set up Permissions in Glassfy, you need to set up Entitlements in Qonversion.

Here’s how it was done in Glassfy:

<img alt="" />

Here’s how to do it in Qonversion:

Navigate to the Entitlements and click the **Create Entitlement** button.

<img alt="" />

### Products (SKUs)

Next, you need to create Products similar to  how you created SKUs in Glassfy:

<img alt="" />

To create Products in Qonversion, go to **Entitlements --> Products**  and click **Create Product**.

<img alt="" />

2. Fill in the product details.

<img alt="" />

* **Qonversion Product ID** – create your unique product identifier in Qonversion that corresponds to a unique product on the Apple App Store and Google Play Store. Qonversion SDK will use it to make purchases.

* **AppStore Product ID** – product identifier on Apple App Store. Learn more on how to create [subscriptions on iOS](https://qonversion.io/blog/configure-iap-app-store-connect/).

* **Google Play Product ID** – product identifier on Google Play Console. Learn more on how to set up [Android in-app products ](/docs/android-in-app-products).

* **Google Play Base Plan ID** - identifier of the base plan for Google Play Product. This is used for subscription products. If you're creating an in-app, leave this field empty for in-apps. In Qonversion, you will set up different products for the different base plans of the same product.

* **Associated Entitlements** - choose the entitlements that should be granted once this product is purchased.

<br />

### Remote Configs (instead of Glassfy Offerings)

Here's what your Offering setup looked like at Glassfy:

<img alt="" />

In Qonversion, this is covered by [Remote Configs](remote-config): create a configuration with a context key (e.g. `main_paywall`) and put your product IDs into the JSON payload in the order you want to display them:

```json theme={null}
{
  "products": ["weekly_premium", "annual_premium_trial"]
}
```

<Frame>
  <img />
</Frame>

Beyond changing products without an app release, Remote Configs also let you [target user segments](remote-config#5-segment-users) and [run A/B tests](launch-test-from-remote-config). See [the payload convention and code samples](migrate-offerings-to-remote-configs) for details.

Now, move to installing your SDK and getting your hands into the code a bit.

## Install the SDK

Check out the links below for the SDK you need and follow the steps provided:

→ [iOS SDK](/docs/ios-sdk-setup)\
→ [Android SDK](/docs/android-sdk)
→ [Flutter SDK](/docs/flutter-sdk)
→ [React Native SDK](/docs/react-native-sdk)
→ [Unity SDK](/docs/unity-sdk)
→ [Cordova Plugin](/docs/cordova)
→ [Capacitor Plugin](/docs/capacitor)
→ [Web](/docs/web-sdk)
→ [Kids Mode Qonversion SDKs](/docs/kids-mode-sdk)

Read more about [Installing the SDKs](/docs/install-sdk).

<br />

When you're done with the setup, it's time to get into the code!

## Launch SDK

Firstly, you need to initialize the SDK. Here's how you did it in Glassfy:

```swift theme={null}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

  Glassfy.initialize(apiKey: "YOUR_API_KEY", watcherMode: false)

}
```

```objectivec theme={null}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  [Glassfy initializeWithAPIKey:@"YOU_API_KEY" watcherMode:NO];

}
```

```java theme={null}
public class App extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    Glassfy.initialize(this, "YOUR_API_KEY", false, null);
  }
}
```

```kotlin theme={null}
class App : Application() {
  override fun onCreate() {
    super.onCreate()

    Glassfy.initialize(this, "YOUR_API_KEY", false, null)
  }
}
```

```dart Flutter theme={null}
try {

  await Glassfy.initialize('YOU_API_KEY',watcherMode: false);

} catch (e) {
  // error
  [...]
}
```

```javascript React Native theme={null}
try {

  await Glassfy.initialize('YOU_API_KEY', false);

} catch (e) {
  // initialization error
  [...]
}
```

```typescript Capacitor theme={null}
try {
  await Glassfy.initialize({ apiKey: 'YOU_API_KEY', watcherMode: false });
} catch (e) {
  // initialization error
}
```

Here's how you'll do it for Qonversion.

```swift theme={null}
import Qonversion

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    let config = Qonversion.Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
    Qonversion.initWithConfig(config)
  	return true
}
```

```objectivec theme={null}
#import "Qonversion.h"
  
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
    [Qonversion initWithConfig:configuration];
    
    return YES;
}
```

```java theme={null}
import com.qonversion.android.sdk.Qonversion;
import com.qonversion.android.sdk.QonversionConfig;
import com.qonversion.android.sdk.dto.QLaunchMode;

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
                this,
                "projectKey",
                QLaunchMode.SubscriptionManagement
        ).build();
        Qonversion.initialize(qonversionConfig);
    }
}
```

```kotlin theme={null}
import com.qonversion.android.sdk.Qonversion
import com.qonversion.android.sdk.QonversionConfig
import com.qonversion.android.sdk.dto.QLaunchMode

public class App : Application {
    override fun onCreate() {
        super.onCreate()
        val qonversionConfig = QonversionConfig.Builder(
            this,
            "projectKey",
            QLaunchMode.SubscriptionManagement
        ).build()
        Qonversion.initialize(qonversionConfig)
    }
}
```

```dart Flutter theme={null}
import 'package:qonversion_flutter/qonversion_flutter.dart';

final config = new QonversionConfigBuilder(
  'projectKey',
  QLaunchMode.subscriptionManagement
).build();
Qonversion.initialize(config);
```

```javascript React Native theme={null}
import Qonversion, {
  QonversionConfigBuilder,
  LaunchMode,
} from 'react-native-qonversion';

const config = new QonversionConfigBuilder(
  'projectKey',
  LaunchMode.SUBSCRIPTION_MANAGEMENT
).build();
Qonversion.initialize(config);
```

```csharp Unity theme={null}
using QonversionUnity;

private void Start()
{
    QonversionConfig config = new QonversionConfigBuilder(
            "projectKey",
            LaunchMode.SubscriptionManagement
        ).Build();
    Qonversion.Initialize(config);
}
```

```typescript Cordova theme={null}
const config = new Qonversion.ConfigBuilder(
  'projectKey',
  Qonversion.LaunchMode.SUBSCRIPTION_MANAGEMENT,
).build();
Qonversion.initialize(config);
```

```typescript Capacitor theme={null}
import Qonversion, {
  QonversionConfigBuilder,
  LaunchMode,
} from '@qonversion/capacitor-plugin';

const config = new QonversionConfigBuilder(
  'projectKey',
  LaunchMode.SUBSCRIPTION_MANAGEMENT
).build();
Qonversion.initialize(config);
```

<br />

## Displaying products

Glassfy:

```swift theme={null}
Glassfy.offerings { (offerings, err) in
    if let offering = offerings?["premium"] {
        // display your offering's skus
        for sku in offering.skus {
            // sku.extravars
            // sku.product.localizedTitle
            // sku.product.localizedDescription
            // sku.product.price
        }
    }
}
```

```objectivec theme={null}
[Glassfy offeringsWithCompletion:^(GYOfferings *offers, NSError *err) {
    GYOffering *offering = offers[@"premium"];
    if (offering) {
        // display your offering's skus
        for (GYSku *sku in offering.skus) {
            // sku.extravars
            // sku.product.localizedTitle
            // sku.product.localizedDescription
            // sku.product.price
        }
    }
}];
```

```kotlin theme={null}
Glassfy.offerings() { offers, err ->
    offers?.all
        ?.firstOrNull { it.offeringId == "premium" }
        ?.also {
            // display your offering's skus
            for (sku in it.skus) {
                // sku.extravars
                // sku.product.title
                // sku.product.description
                // sku.product.price
            }
        }
}
```

```java theme={null}
Glassfy.offerings(new OfferingsCallback() {
    @Override
    public void onResult(@Nullable Offerings offers, @Nullable GlassfyError err) {
        Offering offering = null;
        if (offers != null) {
            for (Offering o : offers.getAll()) {
                if (o.getOfferingId().equals("premium")) {
                    offering = o;
                }
            }
        }
        if (offering != null) {
            // display your offering's skus
            for (Sku sku : offering.getSkus()) {
                // sku.getExtravars();
                // sku.getProduct().getTitle();
                // sku.getProduct().getDescription();
                // sku.getProduct().getPrice();
            }
        }
    }
});
```

```dart Flutter theme={null}
try {
    var offerings = await Glassfy.offerings();
    var offering = offerings.all
        ?.singleWhere((offering) => offering.offeringId == 'premium');

    offering?.skus?.forEach((sku) {
        // sku.product.description
        // sku.product.price
    });
} catch (e) {
  // initialization error
  [...]
}
```

```typescript React Native theme={null}
try {
    let offering = await Glassfy.offerings().all.find((o) => o.offeringId === 'premium');

    offering?.skus.forEach((sku) => {
      // sku.extravars
      // sku.product.description;
      // sku.product.price
    });
} catch (e) {
  [...]
}
```

```typescript Capacitor theme={null}
try {
    let offering = offerings.all.find((o) => o.identifier === 'premium_offering');

    offering?.skus.forEach((sku) => {
      // sku.extravars
      // sku.product.description;
      // sku.product.price
    });
} catch (e) {
  [...]
}
```

<br />

Qonversion — request the Remote Config holding your product IDs, then resolve them to store products:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig(contextKey: "main_paywall") { remoteConfig, error in
      guard let payload = remoteConfig?.payload,
            let productIds = payload["products"] as? [String] else { return }

      Qonversion.shared().products { allProducts, error in
          let paywallProducts = productIds.compactMap { allProducts[$0] }
          // Display paywallProducts in the configured order
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig("main_paywall", object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          val productIds = (remoteConfig.payload["products"] as? List<*>)
              ?.filterIsInstance<String>() ?: return

          Qonversion.shared.products(object : QonversionProductsCallback {
              override fun onSuccess(products: Map<String, QProduct>) {
                  val paywallProducts = productIds.mapNotNull { products[it] }
                  // Display paywallProducts in the configured order
              }

              override fun onError(error: QonversionError) { /* handle error */ }
          })
      }

      override fun onError(error: QonversionError) { /* handle error */ }
  })
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: 'main_paywall');
  final productIds = List<String>.from(remoteConfig.payload['products'] as List);

  final products = await Qonversion.getSharedInstance().products();
  final paywallProducts = productIds
      .map((id) => products[id])
      .whereType<QProduct>()
      .toList();
  // Display paywallProducts in the configured order
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('main_paywall');
  const productIds: string[] = remoteConfig.payload['products'] ?? [];

  const products = await Qonversion.getSharedInstance().products();
  const paywallProducts = productIds
    .map((id) => products.get(id))
    .filter((product) => product != null);
  // Display paywallProducts in the configured order
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig("main_paywall", (remoteConfig, error) =>
  {
      if (error != null) return;
      var productIds = remoteConfig.Payload["products"] as List<object>;

      Qonversion.GetSharedInstance().Products((products, productsError) =>
      {
          if (productsError != null) return;
          // Pick products by the IDs from the payload and display them
      });
  });
  ```
</CodeGroup>

[See the full guide: products via Remote Configs](migrate-offerings-to-remote-configs)

## Making purchases

Glassfy:

```swift theme={null}
Glassfy.purchase(sku: premiumSku) { (transaction, e) in
    // update app status accordingly
    if let p = transaction?.permissions["premium"] {
        if p.isValid {
            // unlock aFeature
        } else {
            // lock aFeature
        }
    }
}
```

```objectivec theme={null}
[Glassfy purchaseSku:premiumSku completion:^(GYTransaction *transaction, NSError *err) {
    GYPermissions *permissions = transaction.permissions;
    if (permissions) {
        GYPermission *p = permissions[@"premium"];
        if (p.isValid) {
            // unlock aFeature
        }
        else {
            // lock aFeature
        }
    }
}];
```

```java theme={null}
Glassfy.purchase(activity, sku, new PurchaseCallback() {
    @Override
    public void onResult(@Nullable Transaction t, @Nullable GlassfyError err) {
        // update app status accordingly
        Permission permission = null;
        if (t != null) {
            for (Permission p : t.getPermissions().getAll()) {
                if (p.getPermissionId().equals("premium")) {
                    permission = p;
                }
            }
        }
        if (permission != null) {
            if (permission.isValid()) {
              // unlock aFeature
            } else {
              // lock aFeature
            }
        }
    }
});
```

```kotlin theme={null}
Glassfy.purchase(activity, sku) { transaction, err ->
    // update app status accordingly
    transaction?.permissions
        ?.all
        ?.firstOrNull { it.permissionId == "premium" }
        ?.also {
            if (it.isValid) {
                // unlock aFeature
            } else {
                // lock aFeature
            }
        }
}
```

```dart Flutter theme={null}
try {
    var transaction = await Glassfy.purchaseSku(sku);

    var p = transaction.permissions?.all?.singleWhere((permission) => permission.permissionId == 'premium');
    if (p?.isValid==true) {
        // unlock aFeature
    }
    else {
        // lock aFeature
    }
} catch (e) {
  // initialization error
  [...]
}
```

```typescript React Native theme={null}
try {
    const transaction = await Glassfy.purchaseSku(premiumSku );
    const permission = transaction.permissions.all.find((p) => p.permissionId === "premium");
    if (permission && permission.isValid) {
        // unlock aFeature
    }
} catch (e) {
  // initialization error
  [...]
}
```

```typescript Capacitor theme={null}
try {
    const transaction = await Glassfy.purchaseSku({ sku: premiumSku });
    const permission = transaction.permissions.all.find((p) => p.permissionId === "premium");
    if (permission && permission.isValid) {
        // unlock aFeature
    }

} catch (e) {
  // initialization error
  [...]
}
```

<br />

Qonversion:

```swift theme={null}
Qonversion.shared().purchase(product) { (result) in
  if result.isSuccessful {
    if let premium: Qonversion.Entitlement = result.entitlements["premium"], premium.isActive {
      // Grant user access to premium features
    }
  } else if result.isCanceledByUser {
    // Handle canceled purchase
  } else if result.isPending {
    // Handle pending purchase
  } else {
    // Handle errors
  }
}
```

```objectivec theme={null}
[[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
  if (result.isSuccessful) {
    QONEntitlement *premiumEntitlement = result.entitlements[@"premium"];
    if (premiumEntitlement && premiumEntitlement.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceledByUser) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
}];
```

```java theme={null}
Qonversion.getSharedInstance().purchase(this, product, new QonversionPurchaseCallback() {
    @Override
    public void onResult(@NonNull QPurchaseResult result) {
        if (result.isSuccessful()) {
            QEntitlement premium = result.getEntitlements().get("premium");
            if (premium != null && premium.isActive()) {
                // Grant user access to premium features
            }
        } else if (result.isCanceledByUser()) {
            // Handle canceled purchase
        } else if (result.isPending()) {
            // Handle pending purchase
        } else {
            // Handle errors
        }
    }
});
```

```kotlin theme={null}
Qonversion.shared.purchase(this, product, object : QonversionPurchaseCallback {
    override fun onResult(result: QPurchaseResult) {
        when {
            result.isSuccessful -> {
                val premium = result.entitlements["premium"]
                if (premium != null && premium.isActive) {
                    // Grant user access to premium features
                }
            }
            result.isCanceledByUser -> {
                // Handle canceled purchase
            }
            result.isPending -> {
                // Handle pending purchase
            }
            else -> {
                // Handle errors
            }
        }
    }
})
```

```dart Flutter theme={null}
final result = await Qonversion.getSharedInstance().purchaseWithResult(product);

if (result.isSuccess) {
  final premium = result.entitlements?['premium'];
  if (premium != null && premium.isActive) {
    // Grant user access to premium features
  }
} else if (result.isCanceled) {
  // Handle canceled purchase
} else if (result.isPending) {
  // Handle pending purchase
} else {
  // Handle errors
}
```

```javascript React Native theme={null}
const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product);

if (result.isSuccess) {
  const premium = result.entitlements?.get('premium');
  if (premium && premium.isActive) {
    // Grant user access to premium features
  }
} else if (result.isCanceled) {
  // Handle canceled purchase
} else if (result.isPending) {
  // Handle pending purchase
} else {
  // Handle errors
}
```

```csharp Unity theme={null}
Qonversion.GetSharedInstance().Purchase(product, (result) =>
{
    if (result.IsSuccess)
    {
        if (result.Entitlements != null && 
            result.Entitlements.TryGetValue("premium", out var premium) && 
            premium.IsActive)
        {
            // Grant user access to premium features
        }
    }
    else if (result.IsCanceled)
    {
        // Handle canceled purchase
    }
    else if (result.IsPending)
    {
        // Handle pending purchase
    }
    else
    {
        // Handle errors
    }
});
```

```typescript Cordova theme={null}
const result = await Qonversion.getSharedInstance().purchase(product);

if (result.isSuccess) {
  const premium = result.entitlements?.get('premium');
  if (premium && premium.isActive) {
    // Grant user access to premium features
  }
} else if (result.isCanceled) {
  // Handle canceled purchase
} else if (result.isPending) {
  // Handle pending purchase
} else {
  // Handle errors
}
```

```typescript Capacitor theme={null}
const result = await Qonversion.getSharedInstance().purchase(product);

if (result.isSuccess) {
  const premium = result.entitlements?.get('premium');
  if (premium && premium.isActive) {
    // Grant user access to premium features
  }
} else if (result.isCanceled) {
  // Handle canceled purchase
} else if (result.isPending) {
  // Handle pending purchase
} else {
  // Handle errors
}
```

The "`product`" here is the Qonversion Product you created earlier.

<br />

## Subscription status

To check the subscription status in Qonversion, you will use Entitlements. In Glassfy, you used Permissions.

Glassfy:

```swift theme={null}
Glassfy.permissions { permissions, err in
    guard let permissions = permissions else { return }
    for p in permissions.all {
        switch (p.permissionId) {
        case "aPermission":
            if (p.isValid) {
                // unlock aFeature
            }
            break;
        default:
            print("Permission not handled");
            break;
        }
    }
}
```

```objectivec theme={null}
[Glassfy permissionsWithCompletion:^(GYPermissions *permission, NSError *err) {
    NSArray<GYPermission*> *permissions = permission.all;
    if (permissions) {
        for (GYPermission *p in permissions) {
            switch (p.permissionId) {
            case @"premium":
                if (p.isValid) {
                    // unlock aFeature
                }
                
                break;
            default:
                NSLog(@"Permission not handled");
                break;
            }
        }
    }
}];
```

```kotlin theme={null}
Glassfy.permissions { permission, err ->
    // update app status accordingly
    permission?.all?.forEach {
        when (it.permissionId) {
            "premium" ->
                if (it.isValid) {
                    // unlock aFeature
                } 
            else -> println("Permission not handled");
        }
    }
}
```

```java theme={null}
Glassfy.permissions(new PermissionsCallback() {
    @Override
    public void onResult(@Nullable Permissions permission, @Nullable GlassfyError error) {
        // update app status accondingly
        if (permission != null) {
            for (Permission p: permission.getAll()) {
                switch (p.getPermissionId()) {
                case "premium":
                    if (p.isValid()) {
                        // unlock aFeature
                    } 
                    break;
                default:
                    Log.d(TAG, "Permission not handled");
                }
            }
        }
    }
});
```

```dart Flutter theme={null}
try {
var permission = await Glassfy.permissions();
      permission.all?.forEach((p)=> {
        if (p.permissionId == "premium" && p.isValid==true) {
          // unlock aFeature
        }
      });
} catch (e) {
  // initialization error
  [...]
}
```

```typescript React Native theme={null}
try {
    const permissions = await Glassfy.permissions();
    permissions.forEach((p)=>{
        switch (p.permissionId) {
            case "premium":
                if (permission.isValid) {
                    // unlock 
                }
                break;
        
            default:
                break;
        }
    });

} catch (e) {
  // initialization error
  [...]
}
```

```typescript Capacitor theme={null}
try {
    const permissions = Glassfy.permissions();
    const permission = transaction.permissions.all.find((p) => p.permissionId === "premium");
    if (permission && permission.isValid) {
        // unlock aFeature
    }

} catch (e) {
  // initialization error
  [...]
}
```

Qonversion:

```swift theme={null}
Qonversion.shared().checkEntitlements { (entitlements, error) in
  if let error = error {
    // handle error
    return
  }
  
  if let premium: Qonversion.Entitlement = entitlements["premium"], premium.isActive {
    // unlock feature
  }
}
```

```objectivec theme={null}
[[Qonversion sharedInstance] checkEntitlements:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull entitlements,
                                NSError * _Nullable error) {
    QONEntitlement *premiumEntitlement = entitlements[@"premium"];
    if (premiumEntitlement && premiumEntitlement.isActive) {
      // unlock feature
    }
}];
```

```java theme={null}
Qonversion.getSharedInstance().checkEntitlements(new QonversionEntitlementsCallback() {
    @Override
    public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
        final QEntitlement premiumEntitlement = entitlements.get("premium");

        if (premiumEntitlement != null && premiumEntitlement.isActive()) {
            // unlock feature
        }
    }

    @Override
    public void onError(@NotNull QonversionError error) {
        // handle error here
    }
});
```

```kotlin theme={null}
Qonversion.shared.checkEntitlements(object: QonversionEntitlementsCallback {
    override fun onSuccess(entitlements: Map<String, QEntitlement>) {
        val premiumEntitlement = entitlements["premium"]
        if (premiumEntitlement != null && premiumEntitlement.isActive) {
            // unlock feature
        }
    }

    override fun onError(error: QonversionError) {
        // handle error here
    }
})
```

```dart Flutter theme={null}
try {
  final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().checkEntitlements();
  final premium = entitlements['premium'];
  if (premium != null && premium.isActive) {
    // unlock feature
  }
} catch (e) {
  print(e);
}
```

```javascript React Native theme={null}
try {
  const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

  const premiumEntitlement = entitlements.get('premium');
  if (premiumEntitlement != null) {
    // unlock feature
  }
} catch (e) {
  // handle error here
}
```

```csharp Unity theme={null}
Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
{
    if (error == null)
    {
        if (entitlements.TryGetValue("premium", out Entitlement premium) && premium.IsActive)
        {
            // unlock feature
        }
    }
    else
    {
        // Handle the error  
        Debug.Log("Error" + error.ToString());
    }
});
```

```typescript Cordova theme={null}
try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
        // unlock feature
    }
} catch (e) {
    // handle error here
}
```

```typescript Capacitor theme={null}
try {
  const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

  const premiumEntitlement = entitlements.get('premium');
  if (premiumEntitlement != null) {
    // unlock feature
  }
} catch (e) {
  // handle error here
}
```

## Authorization system

> 📘 Cross-device and cross-platform access
>
> Set up this section only if you need cross-device and cross-platform access and your project includes an authorization system.

Qonversion lets you identify your signed-in users and unlock premium access across multiple devices. Use the `identify()` method to link a user to your signed-in subscriber. Call this method every time you want to use User Identity. For example, when a user logs in.\
User Identity provides a convenient way of managing premium access of your existing subscribers, including the following cases:

* A user reinstalls your app for any reason. Using the same User ID allows you to provide premium access linked to previously purchased products.
* A user logs in on several devices. You can provide premium access based on a subscription purchased on one of his devices.
* A user logs in on iOS and Android versions of your app. You can provide premium access based on a subscription purchased on one of the platforms.

### Logging in

When a user logs into his account, call `identify()`.

```swift theme={null}
Qonversion.shared().identify("your_custom_user_id")

// or the following option, if you want to get notified about the result.

Qonversion.shared().identify("your_custom_user_id") { user, error in
  // use user if necessary
}
```

```objectivec theme={null}
[[Qonversion sharedInstance] identify:@"your_custom_user_id"];

// or the following option, if you want to get notified about the result.

[[Qonversion sharedInstance] identify:@"your_custom_user_id" completion:^(QONUser * _Nullable user, NSError * _Nullable error) {
  // use user if necessary
}];
```

```java theme={null}
Qonversion.getSharedInstance().identify("your_custom_user_id");

// or the following option, if you want to get notified about the result.

Qonversion.getSharedInstance().identify("your_custom_user_id", new QonversionUserCallback() {
    @Override
    public void onSuccess(@NonNull QUser user) {
        // use user if necessary
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // handle error here
    }
});
```

```kotlin theme={null}
Qonversion.shared.identify("your_custom_user_id")

// or the following option, if you want to get notified about the result.

Qonversion.shared.identify("your_custom_user_id", object : QonversionUserCallback {
    override fun onSuccess(user: QUser) {
        // use user if necessary
    }

    override fun onError(error: QonversionError) {
        // handle error here
    }
})
```

```dart Flutter theme={null}
try {
  final userInfo = await Qonversion.getSharedInstance().identify("your_custom_user_id");
  // use userInfo if necessary
} catch (e) {
  // handle error here
}
```

```javascript React Native theme={null}
try {
  const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
  // use userInfo if necessary
} catch (e) {
  // handle error here
}
```

```csharp Unity theme={null}
Qonversion.GetSharedInstance().Identify("your_custom_user_id")

// or the following option, if you want to get notified about the result.

Qonversion.GetSharedInstance().Identify("your_custom_user_id", (userInfo, error) =>
{
    if (error == null)
    {
        // use userInfo if necessary
    }
    else
    {
        // Handle the error  
        Debug.Log("Error" + error.ToString());
    }
});
```

```typescript Cordova theme={null}
try {
  const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
  // use userInfo if necessary
} catch (e) {
  // handle error here
}
```

```typescript Capacitor theme={null}
try {
  const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
  // use userInfo if necessary
} catch (e) {
  // handle error here
}
```

```curl theme={null}
curl --location --request POST 'https://api.qonversion.io/v3/identities/new_identities_user' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "QON_38a2d811afd54a433587620f8696266e"
}'

{
    "id": "new_identities_user",
    "user_id": "QON_38a2d811afd54a433587620f8696266e"
}
```

> 🚧 Use the unique user ID stored in your database
>
> Always use unique user ID values. Otherwise, a user can get matched to another user's entitlements status.

To check entitlements for identified users,  you can call the `checkEntitlements` function, which we discussed above.

### Logging out

You need to call the `logout()` method to handle entitlements for an unauthorized user.\
Call this method when a user logs out within your app:

```swift theme={null}
Qonversion.shared().logout()
```

```objectivec theme={null}
[[Qonversion sharedInstance] logout];
```

```java theme={null}
Qonversion.getSharedInstance().logout();
```

```kotlin theme={null}
Qonversion.shared.logout()
```

```dart Flutter theme={null}
Qonversion.getSharedInstance().logout();
```

```javascript React Native theme={null}
Qonversion.getSharedInstance().logout();
```

```csharp Unity theme={null}
Qonversion.GetSharedInstance().Logout();
```

```typescript Cordova theme={null}
Qonversion.getSharedInstance().logout();
```

```typescript Capacitor theme={null}
Qonversion.getSharedInstance().logout();
```

When a user logs back into his account, don't forget to use `identify()` method again.

## User-base migration

Those steps have to be done to keep the system working smoothly for your current user base. The necessity of steps depends on the complexity of your system. The simplest system is represented by a single platform infrastructure (Apple, Google, or Stripe). The complex one includes a few platforms with authorization system, your backend infrastructure, and WebHooks handler.

### Client-side migration

Follow these steps to sync user status and retrieve the latest data from Google and Apple on your current device. Call the `syncHistoricalData()` method right after Qonversion SDK initialization to synchronize all the device-related data and ensure that none of the entitlements has been missed.

> ⚠️ Qonversion Android SDK 9.+ limitation
>
> For Qonversion Android SDK 9.+, the method `syncHistoricalData()` has been removed because of a limitation in Google Play Billing Library 8, which prevents the retrieval of historical purchases

### User-database migration

Once you have the app version with Qonversion SDK up and running, it's time to proceed to the server-side migration.

1. Prepare files with [AppStore with Base64 encoded receipt data](/docs/migrating-subscriptions#app-store-data-migration-file) or [Google Play with purchase tokens](/docs/migrating-subscriptions#google-play-data-migration-file).\
   If you do not have receipt data or purchase tokens on your side but are already running your subscription management with a third-party vendor, you should ask the vendor’s support team for the required data file.
2. Then simply **share the files with us** using our support chat and provide CSV files.

## Release

Once you're done with these steps go ahead and release your app. For complex systems with cross-platform access and authorization setups, make sure you're in touch with us and our team has verified your user database migration.


# Google Ads
Source: https://documentation.qonversion.io/docs/google-ads

Optimise your Google App campaigns based on Qonversion events

Qonversion enriches Firebase data with the [corresponding integration](firebase) allowing you to both optimise your Google Ads campaign leveraging [Qonversion revenue events](integrations-overview#tracked-events) or launch interest-based advertising.

## 1. Link Firebase to Qonversion

Here we have a quick overview of all the necessary steps:

1. Connect Firebase SDK to your App
2. Create Data Stream in Google Analytics
3. Provide us with *FirebaseAppInstanceId*, *Firebase App ID* and *Measurement Protocol API secret*

More details you can find on the [following page](firebase)

## 2. Link your Firebase project with your Google Ads account

To successful setup, you need to perform four steps:

1. Open the Firebase project setting menu.
2. Follow to the Integrations tab.
3. Link Google Ads to your Firebase project.
4. On the *Events* tab, In the row for Qonversion events, turn on the switch in the *Mark as conversion* column.

More details you can find in the following links:

1. [Link your Google Ads account to the Firebase project](https://support.google.com/firebase/answer/6383833#zippy=%2Cin-this-article)
2. [Enable Firebase events as conversions](https://support.google.com/firebase/answer/6317522#enable\&zippy=%2Cin-this-article)
3. [Use Firebase events as conversion events in Google Ads](https://support.google.com/google-ads/answer/6366292)
4. [Target audiences using Firebase data](https://support.google.com/google-ads/answer/6398643)

## 3. Leverage the robust Qonversion infrastrucure

Congratulations! Now Qonversion helps you not just successfully process subscription purchases and renewals but also allows you to increase your Ads performance via optimising campaigns by *Trial Started, Trial Converted, Subscription Started, Subscription Renewed* and [other events](integrations-overview#tracked-events).

***

[Firebase](firebase)

[Google Cloud Storage](google-cloud-storage)


# Google Cloud Storage
Source: https://documentation.qonversion.io/docs/google-cloud-storage

Send raw data reports directly to your Google Cloud storage

Qonversion allows you to upload all the raw revenue data we track to your Google Cloud Storage bucket. You can find more details about raw data reports [here](scheduled-reports).

## Prepare Google Cloud Storage credentials

To upload raw data reports to your bucket, Qonversion needs the service account's key and write access to the corresponding bucket.

1. Navigate to the [IAM](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) in your Google Cloud account and select your project.

<img alt="2790" />

2. Create a new service account for the Qonversion file uploader using the *+ CREATE SERVICE ACCOUNT BUTTON*.

<img alt="2786" />

3. Fill fields up only in the first step. Access will be granted further.

<img alt="2780" />

4. Create and download a private JSON key by clicking the *ADD KEY* button in the *KEYS* section.

<img alt="2778" />

5. Navigate to the *DETAILS* section and copy the Email value from the newly created service account. It will be needed in the following steps to grant bucket write access to the account.

<img alt="2772" />

6. Navigate to the [Buckets page](https://console.cloud.google.com/storage/browser) in the Google Cloud Storage.
7. Select existing or create a new bucket for Raw Data reports from Qonversion.
8. Navigate to the *PERMISSIONS* section and click *GRANT ACCESS*

<img alt="2784" />

9. Enter the service account's Email from the 5th step above and select the *Storage Object Creator* role. Click *SAVE*.

<img alt="1674" />

10. Save the bucket's name for further steps.

<img alt="2786" />

11. Congratulations! Now you have finished the preparation steps in the Google Cloud console. The only thing left is to enter the bucket's name and provide previously downloaded private key JSON to Qonversion.

## Enter Google Cloud Storage credentials to Qonversion

1. Navigate to the [Google Cloud Storage](https://dash.qonversion.io/app/integration/create?name=google_cloud_storage) integration creation page.

<img alt="2184" />

2. Enter data from the private key JSON and the bucket's name to the *Service Account credentials JSON* and *Bucket name* fields, respectively.

   * You have gotten the private key JSON during the 4th step in the *Prepare Google Cloud Storage credentials* above.
   * You have gotten the bucket's name during the 9th step in the *Prepare Google Cloud Storage credentials* above.

3. Click *the Add new integration +* button

4. Congratulation! Now you have successfully connected the Google Cloud Storage bucket to Qonversion. Navigate to the [Scheduled reports section](scheduled-reports#google-cloud-storage) to launch report uploading to the bucket.

***

What’s Next

* [Scheduled Reports](scheduled-reports)


# Google Developer Notifications
Source: https://documentation.qonversion.io/docs/google-developer-notifications

Enable Google Real-Time Developer Notifications to speed up event delivery and make Qonversion analytics for Android subscriptions more real-time.

Enabling [Google Real-Time Developer Notifications](https://developer.android.com/google/play/billing/rtdn-reference) speeds up events delivery time for integrations and webhooks and makes data in Qonversion analytics more real-time.

## Google Developer Notifications Setup

<Note>
  If you haven't completed the [Android Store setup](android-store-setup) yet, do that first — it enables the Pub/Sub API and configures the service account credentials, both prerequisites for the steps below.
</Note>

1. Open your project's **Settings → Stores → Android Store** and copy the **Google Developer Notifications Topic ID** shown there.

<img alt="" />

2. Open the **Google Play Console** for your application, then navigate to **Monetization setup**.
3. In the **Real-time developer notifications** section:

* check the **Enable real-time notifications** toggle,
* insert your topic ID,
* choose the correct **Notification content** for your app (with in-app products if you use them),
* click on **Save changes**,
* click on the **Send Test Notification** button.

<img alt="" />

<Warning>
  ### Wait 24 hours before updating your existing key in Qonversion

  It takes up to 24 hours for your [Google service credentials](android-store-setup) to work correctly. Make sure to wait for at least 24 hours after you have created the credentials before connecting to Google Real-Time Developer Notifications.
</Warning>

## Troubleshooting

### Could not connect Qonversion to Google

1. Ensure the provided service access key has Pub/Sub Admin role. Create a new service account key with Pub/Sub Admin role as described [here](android-store-setup#3-create-a-service-account).
2. Wait 24 hours
3. Back up your existing key from Qonversion, then update the service key
4. Try again connecting Google to Qonversion

***

[Apple Server-to-Server Notifications (S2S)](ios-s2s-notifications)

[Migrating In-App Subscriptions](migrating-subscriptions)


# Google Play Store
Source: https://documentation.qonversion.io/docs/google-play

Welcome to the Google Play Store Resources section. This concise guide provides the technical insights and tools to optimize your Android app's performance. Sell digital products and content in your Android apps with one-time and subscription in-app offers. Qonversion makes implementing Google Play's billing system easier, so you can focus on building your app.

***

What’s Next

* [Google Play Data Safety](google-play-data-safety)
* [Upgrade and Downgrade in Google](google-upgrade-downgrade-or-change-subscription)
* [Android test devices](android-test-devices)
* [License testing](license-testing)
* [Publish your Android App](app-publication-in-google-play-console)
* [Android In-App Products Setup](android-in-app-products)
* [Creating an App in Google Play Console](app-creation-in-google-play-console)


# Google Play Data Safety
Source: https://documentation.qonversion.io/docs/google-play-data-safety

The Data safety section on Google Play is a simple way for you to help people understand what user data your app collects or shares, as well as showcase your app’s key privacy and security practices.

You need to provide to Google the information about how your application collects and handles user data including all the libraries you use in the app.

We have prepared a short guide on data that Qonversion collects to help you provide the required information to Google Play.

## Data collection and security

<img alt="1760" />

## Data types

Below is the list of the data types that Google requires to report. We have indicated if Qonversion collects any specific type of data.

| Data Type                     | Details                                                                                                                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Location                      | Not collected by Qonversion                                                                                                                                  |
| Health and Fitness            | Not collected by Qonversion                                                                                                                                  |
| Photos and Videos             | Not collected by Qonversion                                                                                                                                  |
| Files and Docs                | Not collected by Qonversion                                                                                                                                  |
| Calendar                      | Not collected by Qonversion                                                                                                                                  |
| Contacts                      | Not collected by Qonversion                                                                                                                                  |
| User Content                  | Not collected by Qonversion                                                                                                                                  |
| Browsing History              | Not collected by Qonversion                                                                                                                                  |
| Search History                | Not collected by Qonversion                                                                                                                                  |
| App Info and Performance      | Not collected by Qonversion                                                                                                                                  |
| Web Browsing                  | Not collected by Qonversion                                                                                                                                  |
| Contact Info                  | Not collected by Qonversion. *You can choose to use Qonversion [User Properties](user-properties) to store user name, email, and other contact information.* |
| Financial Info                | **Qonversion collects App Stores purchases history**                                                                                                         |
| Personal Info and Identifiers | **Qonversion collects User ID and Device ID.**                                                                                                               |
| Other Data                    | **Qonversion collects data on device OS, make, model, and resolution.**                                                                                      |

## Data usage and handling

<img alt="1878" />

<img alt="1874" />

<img alt="1912" />

<img alt="1938" />

<img alt="1908" />

<img alt="1900" />

***

[Creating an App in Google Play Console](app-creation-in-google-play-console)

[License testing](license-testing)


# Google Play Product Details
Source: https://documentation.qonversion.io/docs/google-play-product-details

Google Play products have a deeply nested structure of objects, containing different information. In our Android and Cross-platform SDKs, we have represented several wrapping classes, containing all the information received from Google Play Billing Library. Below are the specifications of those classes.

`QProductStoreDetails` class contains core information about the store product.

| Field                              | Type                     | Description                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originalProductDetails`           | `ProductDetails`         | Original product details received from Google Play Billing Library.                                                                                                                                                                                                                                                                |
| `basePlanId`                       | `String`                 | Identifier of the base plan to which these details relate. `Null` for in-app products or if not specified in the Qonversion Dashboard.                                                                                                                                                                                             |
| `productId`                        | `String`                 | Identifier of the subscription or the in-app product.                                                                                                                                                                                                                                                                              |
| `name`                             | `String`                 | Name of the subscription or the in-app product                                                                                                                                                                                                                                                                                     |
| `title`                            | `String`                 | Title of the subscription or the in-app product. The title includes the name of the app.                                                                                                                                                                                                                                           |
| `description`                      | `String`                 | Description of the subscription or the in-app product.                                                                                                                                                                                                                                                                             |
| `subscriptionOfferDetails`         | `QProductOfferDetails[]` | Offer details for the subscription. Offer details contain all the available variations of purchase offers, including both base plan and eligible base plan + offer combinations from Google Play Console for the current `basePlanId`. `Null` for in-app products or if `basePlanId` is not specified in the Qonversion Dashboard. |
| `defaultSubscriptionOfferDetails`  | `QProductOfferDetails`   | The most profitable subscription offer for the client in our opinion from all the available offers. We calculate the cheapest price for the client by comparing all the trial or intro phases along with the base plan.                                                                                                            |
| `basePlanSubscriptionOfferDetails` | `QProductOfferDetails`   | Subscription offer details containing only the base plan without any offer.                                                                                                                                                                                                                                                        |
| `inAppOfferDetails`                | `QProductInAppDetails`   | Offer details for the in-app product. `Null` for subscriptions.                                                                                                                                                                                                                                                                    |
| `hasTrialOffer`                    | `Boolean`                | `True`, if there is any eligible offer with a trial for this subscription and base plan combination. `False` otherwise or for an in-app product.                                                                                                                                                                                   |
| `hasIntroOffer`                    | `Boolean`                | `True`, if there is any eligible offer with an intro price for this subscription and base plan combination. `False` otherwise or for an in-app product.                                                                                                                                                                            |
| `hasTrialOrIntroOffer`             | `Boolean`                | `True`, if there is any eligible offer with a trial or an intro price for this subscription and base plan combination. `False` otherwise or for an in-app product.                                                                                                                                                                 |
| `productType`                      | `QProductType`           | The calculated type of the current product.                                                                                                                                                                                                                                                                                        |
| `isInApp`                          | `Boolean`                | `True`, if the product type is `InApp`.                                                                                                                                                                                                                                                                                            |
| `isSubscription`                   | `Boolean`                | `True`, if the product type is `Subscription`.                                                                                                                                                                                                                                                                                     |
| `isPrepaid`                        | `Boolean`                | `True`, if the subscription product is prepaid, which means that users pay in advance - they will need to make a new payment to extend their plan.                                                                                                                                                                                 |
| `isInstallment`                    | `Boolean`                | `True`, if the subscription is an installment plan (the user commits to a fixed number of upfront payments). `False` otherwise or for an in-app product.                                                                                                                                                                           |

`QProductOfferDetails` class contains all the information about the Google subscription offer details. It might be either a plain base plan details or a base plan with concrete offer details.

| Field                    | Type                             | Description                                                                                                                                              |
| ------------------------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originalOfferDetails`   | `SubscriptionOfferDetails`       | Original subscription offer details received from Google Play Billing Library.                                                                           |
| `basePlanId`             | `String`                         | The identifier of the current base plan.                                                                                                                 |
| `offerId`                | `String`                         | The identifier of the concrete offer, to which these details belong. `Null`, if these are plain base plan details.                                       |
| `offerToken`             | `String`                         | A token to purchase the current offer.                                                                                                                   |
| `tags`                   | `String[]`                       | List of tags set for the current offer.                                                                                                                  |
| `pricingPhases`          | `QProductPricingPhase[]`         | A time-ordered list of pricing phases for the current offer.                                                                                             |
| `basePlan`               | `QProductPricingPhase`           | A base plan phase details.                                                                                                                               |
| `installmentPlanDetails` | `QProductInstallmentPlanDetails` | Installment-plan details, if the offer is an installment plan. `Null` otherwise.                                                                         |
| `trialPhase`             | `QProductPricingPhase`           | A trial phase details, if exists.                                                                                                                        |
| `introPhase`             | `QProductPricingPhase`           | An intro phase details, if exists. The intro phase is one of single or recurrent discounted payments.                                                    |
| `hasTrial`               | `Boolean`                        | `True`, if there is a trial phase in the current offer. `False` otherwise.                                                                               |
| `hasIntro`               | `Boolean`                        | `True`, if there is any intro phase in the current offer. `False` otherwise. The intro phase is one of single or recurrent discounted payments.          |
| `hasTrialOrIntro`        | `Boolean`                        | `True`, if there is any trial or intro phase in the current offer. `False` otherwise. The intro phase is one of single or recurrent discounted payments. |

`QProductPricingPhase` class represents a pricing phase, describing how a user pays at a point in time.

| Field                  | Type                                  | Description                                                                                                                          |
| ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `originalPricingPhase` | `PricingPhase`                        | Original pricing phase received from Google Play Billing Library                                                                     |
| `price`                | `QProductPrice`                       | Price for the current phase.                                                                                                         |
| `billingPeriod`        | `QSubscriptionPeriod`                 | The billing period for which the given price applies.                                                                                |
| `billingCycleCount`    | `Int`                                 | Number of cycles for which the billing period is applied.                                                                            |
| `recurrenceMode`       | `QProductPricingPhase.RecurrenceMode` | Recurrence mode for the pricing phase.                                                                                               |
| `type`                 | `QProductPricingPhase.Type`           | Type of the pricing phase.                                                                                                           |
| `isTrial`              | `Boolean`                             | `True`, if the current phase is a trial period. `False` otherwise.                                                                   |
| `isIntro`              | `Boolean`                             | `True`, if the current phase is an intro period. False otherwise. The intro phase is one of single or recurrent discounted payments. |
| `isBasePlan`           | `Boolean`                             | `True`, if the current phase represents the base plan. `False` otherwise.                                                            |

`QSubscriptionPeriod` class describes a subscription period.

| Field       | Type                       | Description                                                               |
| ----------- | -------------------------- | ------------------------------------------------------------------------- |
| `unitCount` | `Int`                      | A count of subsequent intervals.                                          |
| `unit`      | `QSubscriptionPeriod.Unit` | Interval unit.                                                            |
| `iso`       | `String`                   | ISO 8601 representation of the period, e.g. "P7D", meaning 7 days period. |

`QProductInstallmentPlanDetails` class describes the installment plan for a subscription offer (Google Play installment plans, where the user commits to a fixed number of upfront payments before the subscription falls back to a regular renewable plan).

| Field                               | Type                     | Description                                                                                                                                                     |
| ----------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originalInstallmentPlanDetails`    | `InstallmentPlanDetails` | Original `InstallmentPlanDetails` received from Google Play Billing Library.                                                                                    |
| `commitmentPaymentsCount`           | `Int`                    | Committed payments count after a user signs up for this subscription plan.                                                                                      |
| `subsequentCommitmentPaymentsCount` | `Int`                    | Subsequent committed payments count after this subscription plan renews. `0` if the plan has no subsequent commitment and falls back to a regular monthly plan. |

`QProductInAppDetails` class contains all the information about the Google in-app product details.

| Field                                 | Type                          | Description                                                                         |
| ------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------- |
| `originalOneTimePurchaseOfferDetails` | `OneTimePurchaseOfferDetails` | Original one-time purchase offer details received from Google Play Billing Library. |
| `price`                               | `QProductPrice`               | The price of the in-app product.                                                    |

`QProductPrice` class contains information about the product's price.

| Field               | Type       | Description                                                                                       |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `priceAmountMicros` | `Long`     | Total amount of money in micro-units, where 1,000,000 micro-units equal one unit of the currency. |
| `priceCurrencyCode` | `String`   | ISO 4217 currency code for price.                                                                 |
| `formattedPrice`    | `String`   | Formatted price for the payment, including its currency sign.                                     |
| `isFree`            | `Boolean`  | `True`, if the price is zero. `False` otherwise.                                                  |
| `currency`          | `Currency` | Currency object from the `priceCurrencyCode`. `Null` if failed to parse.                          |
| `currencySymbol`    | `String`   | Price currency symbol. `Null` if failed to parse.                                                 |

`QSubscriptionPeriod.Unit` is the enumeration of the following values: `Day`, `Week`, `Month`, `Year`, `Unknown`.

`QProductPricingPhase.RecurrenceMode` describes the recurrence mode of the pricing phase and contains the following values.

| Value               | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `InfiniteRecurring` | The billing plan payment recurs for infinite billing periods unless canceled. |
| `FiniteRecurring`   | The billing plan payment recurs for a fixed number of billing periods.        |
| `NonRecurring`      | The billing plan payment is a one-time charge that does not repeat.           |
| `Unknown`           | Unknown recurrence mode.                                                      |

`QProductPricingPhase.Type` describes the type of the pricing phase and contains the following values.

| Value                        | Description                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| `Regular`                    | Regular subscription without any discounts like trial or intro offers. |
| `FreeTrial`                  | A free phase.                                                          |
| `DiscountedSinglePayment`    | A phase with a discounted payment for a single period.                 |
| `DiscountedRecurringPayment` | A phase with a discounted payment for several periods.                 |
| `Unknown`                    | Unknown pricing phase type.                                            |

***

[Restore behavior](transferring)

[Stripe Integration](stripe-integration)


# Upgrade and Downgrade in Google
Source: https://documentation.qonversion.io/docs/google-upgrade-downgrade-or-change-subscription

When upgrading or downgrading a subscription, you can set the update policy, or how the change affects your subscribers. The following table lists available update policies:

| Name                  | Description                                                                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChargeFullPrice`     | The new plan takes effect immediately, and the user is charged full price of new plan and is given a full billing cycle of subscription, plus remaining prorated time from the old plan. |
| `ChargeProratedPrice` | The new plan takes effect immediately, and the billing cycle remains the same.                                                                                                           |
| `WithTimeProration`   | The new plan takes effect immediately, and the remaining time will be prorated and credited to the user.                                                                                 |
| `Deferred`            | The new purchase takes effect immediately, the new plan will take effect when the old item expires.                                                                                      |
| `WithoutProration`    | The new plan takes effect immediately, and the new price will be charged on next recurrence time.                                                                                        |

Upgrading, downgrading, or changing a subscription on the Google Play Store requires calling the `purchase()` function with `setOldProduct` purchase options.

See [Google Play Documentation](https://developer.android.com/google/play/billing/subscriptions#upgrade-downgrade) for more details.

Use Qonversion SDK for upgrading, downgrading, or changing Google Play Store subscription:

<CodeGroup>
  ```java Java theme={null}
  final QPurchaseOptions purchaseOptions = new QPurchaseOptions.Builder()
          .setOldProduct(oldProduct)
          .build();
  Qonversion.getSharedInstance().purchase(this, product, purchaseOptions, new QonversionPurchaseCallback() {
      @Override
      public void onResult(@NonNull QPurchaseResult result) {
          if (result.isSuccessful()) {
              QEntitlement premium = result.getEntitlements().get("premium");
              if (premium != null && premium.isActive()) {
                  // Grant user access to premium features
              }
          } else if (result.isCanceledByUser()) {
              // Handle canceled purchase
          } else if (result.isPending()) {
              // Handle pending purchase
          } else {
              // Handle errors
          }
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  val purchaseOptions = QPurchaseOptions.Builder()
      .setOldProduct(oldProduct)
      .build()
  Qonversion.shared.purchase(this, product, purchaseOptions, object : QonversionPurchaseCallback {
      override fun onResult(result: QPurchaseResult) {
          when {
              result.isSuccessful -> {
                  val premium = result.entitlements["premium"]
                  if (premium != null && premium.isActive) {
                      // Grant user access to premium features
                  }
              }
              result.isCanceledByUser -> {
                  // Handle canceled purchase
              }
              result.isPending -> {
                  // Handle pending purchase
              }
              else -> {
                  // Handle errors
              }
          }
      }
  })
  ```

  ```dart Flutter theme={null}
  // Build purchase options with old product for upgrade/downgrade
  final options = QPurchaseOptionsBuilder()
      .setOldProduct(oldProduct)  // Product to upgrade from
      .setUpdatePolicy(QPurchaseUpdatePolicy.chargeFullPrice)  // Optional: update policy
      .build();

  final QPurchaseResult result = await Qonversion.getSharedInstance().purchaseWithResult(
    newProduct,
    purchaseOptions: options,
  );

  if (result.isSuccess) {
    final premium = result.entitlements?['premium'];
    if (premium != null && premium.isActive) {
      // User successfully upgraded to new subscription
    }
  } else if (result.isCanceled) {
    // Handle canceled upgrade
  } else if (result.isPending) {
    // Handle pending upgrade
  } else {
    // Handle errors
  }
  ```

  ```typescript React Native theme={null}
  // Build purchase options with old product for upgrade/downgrade
  const options = new PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)  // Product to upgrade from
    .setUpdatePolicy(PurchaseUpdatePolicy.CHARGE_FULL_PRICE)  // Optional: update policy
    .build();

  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(
    newProduct,
    options,
  );

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // User successfully upgraded to new subscription
    }
  } else if (result.isCanceled) {
    // Handle canceled upgrade
  } else if (result.isPending) {
    // Handle pending upgrade
  } else {
    // Handle errors
  }
  ```

  ```csharp Unity theme={null}
  // Build purchase options with old product for upgrade/downgrade
  var options = new PurchaseOptionsBuilder()
      .SetOldProduct(oldProduct)  // Product to upgrade from
      .SetUpdatePolicy(PurchaseUpdatePolicy.ChargeFullPrice)  // Optional: update policy
      .Build();

  Qonversion.GetSharedInstance().Purchase(newProduct, options, (result) =>
  {
      if (result.IsSuccess)
      {
          if (result.Entitlements != null &&
              result.Entitlements.TryGetValue("premium", out var premium) &&
              premium.IsActive)
          {
              // User successfully upgraded to new subscription
          }
      }
      else if (result.IsCanceled)
      {
          // Handle canceled upgrade
      }
      else if (result.IsPending)
      {
          // Handle pending upgrade
      }
      else
      {
          // Handle errors
      }
  });
  ```

  ```typescript Cordova theme={null}
  // Build purchase options with old product for upgrade/downgrade
  const options = new Qonversion.PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)  // Product to upgrade from
    .setUpdatePolicy(PurchaseUpdatePolicy.CHARGE_FULL_PRICE)  // Optional: update policy
    .build();

  const result = await Qonversion.getSharedInstance().purchase(
    newProduct,
    options,
  );

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // User successfully upgraded to new subscription
    }
  } else if (result.isCanceled) {
    // Handle canceled upgrade
  } else if (result.isPending) {
    // Handle pending upgrade
  } else {
    // Handle errors
  }
  ```

  ```typescript Capacitor theme={null}
  // Build purchase options with old product for upgrade/downgrade
  const options = new PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)  // Product to upgrade from
    .setUpdatePolicy(PurchaseUpdatePolicy.CHARGE_FULL_PRICE)  // Optional: update policy
    .build();

  const result = await Qonversion.getSharedInstance().purchase(
    newProduct,
    options,
  );

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // User successfully upgraded to new subscription
    }
  } else if (result.isCanceled) {
    // Handle canceled upgrade
  } else if (result.isPending) {
    // Handle pending upgrade
  } else {
    // Handle errors
  }
  ```
</CodeGroup>

***

[Publish your Android App](app-publication-in-google-play-console)

[Sample Apps](sample-apps)


# Qonversion SDK Errors Details
Source: https://documentation.qonversion.io/docs/handling-errors

Here you can find the descriptions of errors that may be returned from the Qonversion SDK. These descriptions are intended to help you troubleshoot any issues quicker.

<Warning>
  Make sure to use a device (not a simulator) when testing iOS purchases.
</Warning>

| iOS enum (Int value)                                  | Android enum                      | Description                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `QONErrorCodeUnknown` (0)                             | `Unknown`                         | An unexpected error occurred that can't be classified                                                                                                                                                                                                                                 |
| `QONErrorCodePurchaseCanceled` (1)                    | `PurchaseCanceled`                | The user canceled the purchase request                                                                                                                                                                                                                                                |
| `QONErrorCodeProductNotFound` (2)                     | `ProductNotFound`                 | This error means that, for some reason, the product is not found. There are a few reasons you can receive this error. See the details for the Product not found error [here](troubleshooting#product-not-found-error)                                                                 |
| `QONErrorCodeClientInvalid` (3)                       |                                   | The client is not allowed to issue the request.                                                                                                                                                                                                                                       |
| `QONErrorCodePaymentInvalid` (4)                      |                                   | The purchase identifier was invalid.                                                                                                                                                                                                                                                  |
| `QONErrorCodePaymentNotAllowed` (5)                   |                                   | This device is not allowed to make the payment.                                                                                                                                                                                                                                       |
| `QONErrorCodeStoreProductNotAvailable` (7)            | `StoreProductNotAvailable`        | The product is not available in the current storefront.                                                                                                                                                                                                                               |
| `QONErrorCodeCloudServicePermissionDenied` (8)        |                                   | Apple StoreKit SKErrorCloudServicePermissionDenied error analog.Available from iOS 9.3, TV OS 9.3, Watch OS 6.2, Mac OS 11.0The user has not allowed access to Cloud service information.                                                                                             |
| `QONErrorCodeCloudServiceNetworkConnectionFailed` (9) |                                   | Apple StoreKit SKErrorCloudServiceNetworkConnection- Failed error analog.Available from iOS 9.3, TV OS 9.3, Watch OS 6.2, Mac OS 11.0The device could not connect to the network.                                                                                                     |
| `QONErrorCodeCloudServiceRevoked` (10)                |                                   | Apple StoreKit SKErrorCloudServiceRevoked error analog.Available from iOS 10.3, TV OS 10.3, Watch OS 6.2, Mac OS 11.0The user has revoked permission to use this cloud service.                                                                                                       |
| `QONErrorCodePrivacyAcknowledgementRequired` (11)     |                                   | Apple StoreKit SKErrorPrivacyAcknowledgementRequired error analog.Available from iOS 12.2, TV OS 12.2, Watch OS 6.2, Mac OS 10.14.4The user needs to acknowledge Apple's privacy.                                                                                                     |
| `QONErrorCodeUnauthorizedRequestData` (12)            |                                   | Apple StoreKit SKErrorUnauthorizedRequestData error analog.Available from iOS 12.2, Watch OS 6.2, Mac OS 10.14.4The app is attempting to use SKPayment's requestData property but does not have the appropriate entitlement.                                                          |
|                                                       | `BillingUnavailable`              | The Billing service is unavailable on the device. Please see the details [here](troubleshooting#billing-unavailable-error).                                                                                                                                                           |
|                                                       | `PurchaseInvalid`                 | Failure to purchase. Please ensure that you are using the Google account where purchases are allowed, and the application was correctly signed and properly set up for billing. Please have a look at the following [guide on setting up the Google Play Store Billing](google-play). |
|                                                       | `ProductNotOwned`                 | Failure to consume the purchase since the item is not owned.                                                                                                                                                                                                                          |
|                                                       | `ProductAlreadyOwned`             | Failure to purchase since the item is already owned.                                                                                                                                                                                                                                  |
|                                                       | `LaunchError`                     | There was an error while launching the Qonversion SDK.                                                                                                                                                                                                                                |
|                                                       | `PurchaseUnspecified`             | Unspecified state of the purchase.                                                                                                                                                                                                                                                    |
| `QONErrorCodeNetworkConnectionFailed` (14)            | `NetworkConnectionFailed`         | Failed to connect to the network.                                                                                                                                                                                                                                                     |
| `QONErrorCodeInternalError` (17)                      |                                   | An internal SDK error occurred (iOS-only).                                                                                                                                                                                                                                            |
| `QONErrorCodeIncorrectRequest` (22)                   |                                   | The SDK request failed (iOS-only).                                                                                                                                                                                                                                                    |
| `QONErrorCodeBackendError` (23)                       | `BackendError`                    | There was an internal backend error.                                                                                                                                                                                                                                                  |
| `QONErrorCodePurchasePending` (18)                    |                                   | The payment transaction is in the queue, but its final status is pending external action.                                                                                                                                                                                             |
| `QONErrorCodeRemoteConfigurationNotAvailable` (19)    | `RemoteConfigurationNotAvailable` | Remote configuration is not available for the current user. Please ensure that the remote configuration is configured correctly in the Qonversion Dashboard.                                                                                                                          |
| `QONErrorCodeFailedToReceiveData` (20)                | `ResponseParsingFailed`           | Something went wrong during the network data deserialization                                                                                                                                                                                                                          |
| `QONErrorCodeResponseParsingFailed` (21)              | `ResponseParsingFailed`           | The response has the wrong format.                                                                                                                                                                                                                                                    |
| `QONErrorCodeInvalidCredentials` (25)                 | `InvalidCredentials`              | The access token is invalid or not set                                                                                                                                                                                                                                                |
| `QONErrorCodeInvalidClientUID` (26)                   | `InvalidClientUid`                | Client Uid is invalid or not set                                                                                                                                                                                                                                                      |
| `QONErrorCodeUnknownClientPlatform` (27)              | `UnknownClientPlatform`           | The current platform is not supported                                                                                                                                                                                                                                                 |
| `QONErrorCodeFraudPurchase` (28)                      | `FraudPurchase`                   | Fraud purchase was detected                                                                                                                                                                                                                                                           |
| `QONErrorCodeFeatureNotSupported` (29)                | `FeatureNotSupported`             | The requested feature is not supported                                                                                                                                                                                                                                                |
| `QONErrorCodeAppleStoreError` (30)                    | `PlayStoreError`                  | There was an issue with the Play Store service (Android) or App Store service (iOS). The store is unavailable, times out, disconnects, or returns an unexpected response.                                                                                                             |
| `QONErrorCodePurchaseInvalid` (31)                    | `PurchaseInvalid`                 | Failure of purchase. For example, a purchase with such `purchaseToken` can't be found. Possible reason: the provided store key exists, but is related to another project.                                                                                                             |
| `QONErrorCodeProjectConfigError` (32)                 | `ProjectConfigError`              | The project is not configured or configured incorrectly in Qonversion's settings dashboard. Check the details [here](troubleshooting#project-config-error-active-store-not-found)                                                                                                     |
| `QONErrorCodeInvalidStoreCredentials` (33)            | `InvalidStoreCredentials`         | This account does not have access to the requested application. Please check the provided Store keys.Check the details [here](troubleshooting#invalid-store-credentials-error)                                                                                                        |
| `QONErrorCodeReceiptValidationError` (34)             |                                   | The provided receipt can't be validated. Check the details [here](troubleshooting#receipt-validation-error)                                                                                                                                                                           |
| `QONErrorCodeApiRateLimitExceeded` (35)               | `ApiRateLimitExceeded`            | There were too many parallel or subsequent requests to the Qonversion API in a while.                                                                                                                                                                                                 |
| `QONErrorCodeOfferingsNotAvailable` (36)              | `OfferingsNotFound`               | No offerings found for the current user. *(legacy Offerings — [migrate to Remote Configs](remote-config))*                                                                                                                                                                            |

***

[Troubleshooting](troubleshooting)

[Rate Limits](rate-limits)


# How Qonversion Works
Source: https://documentation.qonversion.io/docs/how-qonversion-works

Qonversion provides the complete toolset to build, analyze, and grow your mobile subscription business. There are two modes of using Qonversion:

## 1. Subscription Management Mode

Use Qonversion SDK or API methods to process your In-App & Web purchases and to manage user access to the premium features. Qonversion validates user purchases and provides your mobile- or web-based app with an accurate entitlement status. You can quickly implement purchases without headaches with StoreKit or Google Play Billing Library, and you don't need to build your server to validate subscriptions.

→ See the details of setting the SDK and making purchases in [Subscription Management Mode](subscription-management-mode).

## 2. Analytics Mode

Use Qonversion with your in-house entitlement management to get comprehensive subscription analytics, user engagement tools (like A/B testing and no-code builder), and send data to leading marketing, analytics, and engagement platforms.

→ See the [Analytics Mode quick start guide](analytics-mode).

<Info>
  ### Subscription Management Mode includes Analytics Mode

  Subscription Management Mode includes everything from Analytics Mode. In case you already have in-app subscriptions implemented and are not ready to change your current in-app subscription flow, use Analytics Mode.
</Info>

***

[Welcome](qonversion-platform)

[System Reliability](system-reliability)


# In-App Purchase API Key
Source: https://documentation.qonversion.io/docs/in-app-purchase-api-key

How to create an In-App Purchase API key and connect it to Qonversion so we can validate transactions, detect refunds, look up subscription status, and read transaction history.

The **In-App Purchase API key** lets Qonversion call Apple's runtime endpoints with your app's identity. We use it to:

* **Validate every transaction** against the App Store Server API.
* **Detect refunds and consumption decisions** from the live billing system.
* **Look up subscription status and transaction history** when responding to user requests.
* **Sign promotional offer signatures** for the App Store Server API.

<Note>
  This is a **different key** from the [App Store Connect API key](app-store-connect-api-key) you generated for Step 1. They live under different tabs in App Store Connect and they are **not interchangeable** — Apple will reject one if you use it where the other is expected.
</Note>

## 1. Make sure you have the right role

To generate an In-App Purchase API key, your App Store Connect user must have one of these roles:

* **Account Holder**
* **Admin**

Contact your team's Account Holder if you don't have one of these roles. App Manager is **not** sufficient for this key type.

## 2. Open the In-App Purchase tab

1. [Log in](https://appstoreconnect.apple.com/login) to App Store Connect.
2. Click **Users and Access** in the top navigation.
3. Open the **Integrations** tab.
4. Switch to the **In-App Purchase** sub-tab (not "App Store Connect API").
5. Click **Generate In-App Purchase Key** (or **+** if you already have keys).

<Frame>
  <img />
</Frame>

## 3. Generate a new key

1. Give it a clear name, e.g. **Qonversion**.
2. Click **Generate**.

<Frame>
  <img />
</Frame>

## 4. Copy the Key ID and Issuer ID, and download the .p8 private key

Everything you need lives on the same screen — copy the two identifiers and download the key file before leaving:

* Copy the **Key ID** (10-character string in the row of your new key) — this is the **Key Identifier** in Qonversion.
* Above the table, copy the **Issuer ID** (UUID format, e.g. `57246542-96fe-1a63-e053-0824d011072a`) — this is the **Issuer Identifier** in Qonversion.
* In the same row, click **Download API Key** to get the **.p8** file.

<Warning>
  Apple lets you download the `.p8` file **only once**. If you lose it, you have to revoke the key and create a new one. Save it somewhere safe before continuing.
</Warning>

<Frame>
  <img />
</Frame>

## 5. Paste everything into Qonversion

1. Open Qonversion Dash → **Project Settings** → **Stores** → **Apple App Store**.
2. On **Step 3 · Server API access**:
   * Paste the **Key ID** in the **Key Identifier** field.
   * Upload the `.p8` file in the **Private Key** field.
   * Paste the **Issuer ID** in the **Issuer Identifier** field.

<Frame>
  <img />
</Frame>

## Troubleshooting

Step 3 has no preflight Verify button — Apple validates the key when Qonversion makes its first runtime call. Issues surface as failed receipt validations, missing refund events, or empty subscription-status responses.

### Receipts or transactions fail validation (HTTP 401 / NOT\_AUTHORIZED)

* Make sure you pasted the **Key ID**, not the key name.
* Make sure the **Issuer ID** is from the **In-App Purchase** tab, not the App Store Connect API tab.
* Make sure the `.p8` file matches the Key ID you pasted.
* If you previously revoked the old key on Apple's side, the old `.p8` stops working immediately — generate a new key, upload the new `.p8`, and Qonversion switches over on the next call.

### Lost the .p8 file

Apple does not let you re-download the file. Open **Users and Access → Integrations → In-App Purchase**, **revoke** the old key, then generate a new one and re-upload the new `.p8`.

***

## What's next?

After this step, finish the rest of the wizard:

* **Step 4 · Production readiness** — copy the [Server-to-Server Notification URL](ios-s2s-notifications) into App Store Connect.


# Send Paddle Purchases to Qonversion
Source: https://documentation.qonversion.io/docs/initiate-purchase-paddle

Link every Paddle purchase to a Qonversion user — via the web SDK or your server — so Qonversion can grant entitlements and attribute revenue.

Every Paddle purchase must be linked to a Qonversion user so Qonversion can grant entitlements and attribute revenue. There are two ways to do it:

* **Automatic (recommended)** — tag the Paddle Checkout with the Qonversion user in `custom_data`. Qonversion reads it from the Paddle webhook and grants entitlements automatically, including for later renewals, refunds, and cancellations. No purchase-submission call is required.
* **Explicit** — submit the completed purchase yourself from your server (REST API) or the browser (Web SDK), passing the Qonversion user in the request.

## 1. Link the Qonversion user with `custom_data`

When you open the Paddle Checkout, set `custom_data.qonversion_client_uid` to the buyer's Qonversion User ID. Paddle stores it on the resulting transaction and includes it in every webhook it sends — that is how Qonversion maps the purchase (and all future events on the same subscription) to the user.

<CodeGroup>
  ```javascript Paddle.js overlay checkout theme={null}
  Paddle.Checkout.open({
    items: [{ priceId: 'pri_01hv4rrk', quantity: 1 }],
    customData: {
      qonversion_client_uid: '<QONVERSION_USER_ID>',
    },
  });
  ```
</CodeGroup>

<Info>
  The key must be exactly `qonversion_client_uid`. Its value is the Qonversion User ID — see [Getting the Qonversion User ID](#getting-the-qonversion-user-id).
</Info>

If you create transactions or subscriptions with the Paddle API instead of the overlay checkout, set the same `qonversion_client_uid` key on the request's `custom_data`.

### Customer-level fallback

If a webhook payload does not carry `custom_data.qonversion_client_uid`, Qonversion falls back to the Paddle **customer's** `custom_data`. You can set it when you create or update the customer:

<CodeGroup>
  ```bash cURL — Paddle API theme={null}
  curl --request PATCH \
    --url https://api.paddle.com/customers/{customer_id} \
    --header 'Authorization: Bearer {paddle_api_key}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "custom_data": {
        "qonversion_client_uid": "<QONVERSION_USER_ID>"
      }
    }'
  ```
</CodeGroup>

<Warning>
  If neither the transaction nor the customer carries `qonversion_client_uid`, Qonversion acknowledges the Paddle webhook but cannot map the purchase to a user, so no entitlement is granted. Set it at checkout (or on the customer) before the first payment.
</Warning>

### Getting the Qonversion User ID

The Qonversion User ID is the value you place in `qonversion_client_uid` (and in the `{user_id}` of the REST call below). Obtain it in one of two ways:

* **From the SDK** — call the `userInfo()` method and use the `qonversionId` property from the result. See [User Identifiers](/docs/user-identifiers) for details.
* **Via API** — create a user by calling `POST /v3/users/{id}`. See the API reference for details.

## 2. Submit the purchase explicitly

If you prefer to push purchases yourself instead of relying on the automatic webhook mapping, send the completed purchase to Qonversion after a successful payment. Capture the Paddle identifiers from the completed transaction and call:

<Warning>
  The client-side `checkout.completed` event gives you the `transaction_id` (`txn_`) and `product_id` (`pro_`), but **not** the `subscription_id` — Paddle creates the subscription asynchronously a few seconds later. For a subscription purchase, read the `subscription_id` server-side from the `transaction.completed` / `subscription.created` webhook (or `GET /transactions/{id}`) before submitting. For subscriptions, prefer the automatic `custom_data` flow above, which has no such timing constraint.
</Warning>

```bash theme={null}
curl -X POST \
  https://api.qonversion.io/v3/users/{user_id}/purchases \
  -H "Authorization: Bearer {project_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "price": "9.99",
    "paddle_store_data": {
      "type": "subscription",
      "transaction_id": "{paddle_transaction_id}",
      "subscription_id": "{paddle_subscription_id}",
      "product_id": "{paddle_product_id}"
    }
  }'
```

Replace `{paddle_transaction_id}` and `{paddle_subscription_id}` with the values from the completed Paddle transaction, and `{paddle_product_id}` with the Paddle product ID. The `{user_id}` is the Qonversion User ID (see [above](#getting-the-qonversion-user-id)).

| Field                               | Source                                                                                 |
| ----------------------------------- | -------------------------------------------------------------------------------------- |
| `currency`                          | transaction currency code                                                              |
| `price`                             | transaction total                                                                      |
| `paddle_store_data.type`            | `subscription` for recurring products, `non_recurring` for one-time purchases          |
| `paddle_store_data.transaction_id`  | Paddle transaction id (`txn_`)                                                         |
| `paddle_store_data.subscription_id` | Paddle subscription id (`sub_`). Required for `subscription`; omit for `non_recurring` |
| `paddle_store_data.product_id`      | Paddle product id (`pro_`)                                                             |

## Web SDK

If you are using Qonversion on the web, you can also use the [Qonversion Web SDK](/docs/web-sdk) to submit the purchase. After a successful Paddle payment, pass the purchase data to `sendPaddlePurchase`.

<Warning>
  The Web SDK object differs from the REST body above. Its fields are **camelCase** (`transactionId`, `productId`, `subscriptionId`), and the one-time `type` value is **`inapp`**, not `non_recurring` (the SDK maps it to `non_recurring` on the wire for you).
</Warning>

<CodeGroup>
  ```javascript theme={null}
  const purchase = await qonversionInstance.sendPaddlePurchase({
    price: '9.99',
    currency: 'USD',
    transactionId: 'txn_01hv4rrk',
    productId: 'pro_01hv4rrk',
    type: 'subscription',           // or 'inapp' for one-time purchases
    subscriptionId: 'sub_01hv4rrk', // required for 'subscription'; omit for 'inapp'
  });
  ```
</CodeGroup>

See the full [Paddle Integration guide](/docs/paddle-integration) for details.


# Send Stripe Purchases to Qonversion
Source: https://documentation.qonversion.io/docs/initiate-purchase-stripe

Create a Stripe Checkout Session on your server and report the completed purchase to Qonversion so entitlements and revenue analytics stay in sync.

To process purchases via Stripe, you need to create a Stripe Checkout Session on your server and send the purchase data to Qonversion after a successful payment.

## 1. Create a Checkout Session

Create a [Stripe Checkout Session](https://docs.stripe.com/api/checkout/sessions/create) on your server using the Stripe API. Refer to the [Stripe documentation](https://docs.stripe.com/checkout/quickstart) for detailed instructions.

## 2. Send Purchase to Qonversion

After a successful payment, retrieve the Stripe Session data and send the purchase information to Qonversion using the API:

```bash theme={null}
curl -X POST \
  https://api.qonversion.io/v3/users/{user_id}/purchases \
  -H "Authorization: Bearer {project_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "price": "9.99",
    "stripe_store_data": {
      "subscription_id": "{stripe_subscription_id}",
      "product_id": "{qonversion_product_id}"
    }
  }'
```

Replace `{stripe_subscription_id}` with the Stripe subscription ID from the Checkout Session and `{qonversion_product_id}` with the product ID configured in Qonversion.

| Field                               | Source                           |
| ----------------------------------- | -------------------------------- |
| `currency`                          | `stripe_session.currency`        |
| `price`                             | `stripe_session.amount_total`    |
| `stripe_store_data.subscription_id` | `stripe_session.subscription.id` |
| `stripe_store_data.product_id`      | Your Stripe Product ID           |

### Getting the User ID

The `{user_id}` in the request URL is the Qonversion User ID. You can obtain it in two ways:

* **From the SDK** — call the `userInfo()` method and use the `qonversionId` property from the result. See [User Identifiers](/docs/user-identifiers) for details.
* **Via API** — create a user by calling `POST /v3/users/{id}`. See the API reference for details.

## Web SDK

If you are using Qonversion on the web, you can also use the [Qonversion Web SDK](/docs/web-sdk) to handle purchases.

See the full [Stripe Integration guide](/docs/stripe-integration) for details.


# Installing the SDKs
Source: https://documentation.qonversion.io/docs/install-sdk

Install the Qonversion SDK for iOS, Android, Flutter, React Native, Unity, Cordova, Capacitor, Web, and macOS platforms.

Qonversion supports several platforms. Choose the platform of your app and install the SDK.

<CardGroup>
  <Card title="iOS SDK" href="/docs/ios-sdk-setup" />

  <Card title="Android SDK" href="/docs/android-sdk" />

  <Card title="Flutter SDK" href="/docs/flutter-sdk" />

  <Card title="React Native SDK" href="/docs/react-native-sdk" />

  <Card title="Unity SDK" href="/docs/unity-sdk" />

  <Card title="Cordova Plugin" href="/docs/cordova" />

  <Card title="Capacitor Plugin" href="/docs/capacitor" />

  <Card title="Web SDK" href="/docs/web-sdk" />

  <Card title="macOS / Catalyst" href="/docs/macos-catalyst" />
</CardGroup>

<Info>
  ### Activating Kids Mode

  Follow the [documentation](kids-mode-sdk) to enable Kids Mode if you are building an app for kids.
</Info>

<Accordion title="SDK versioning policy">
  This topic explains Qonversion's SDK versioning, which is based on the semantic versioning standard. To learn more, read [Semantic Versioning 2.0.0](https://semver.org/).

  In semantic versioning each version consists of three parts:

  * major version number
  * minor version number
  * patch version number

  For example, for version **2.7.3**, **2** is the major version, **7** is minor, and **3** -- is a patch.

  ### major version number

  Major SDK updates can change API and SDK methods and might be backward incompatible. The major version component increments when the version contains breaking changes. Such updates are very rare.

  ### minor version number

  Minor updates usually add new features, and they are always backward compatible.

  ### patch version number

  Patch updates are usually bug fixes.
</Accordion>

***

[Quick Start](quickstart)

[iOS](ios-sdk-setup)


# Installation
Source: https://documentation.qonversion.io/docs/installation

Connect your app to the Qonversion SDK for the No-Code Builder to handle screen display, product data, analytics, and purchase tracking.

Before you start building screens in the No-Code Builder, make sure your app is connected to the Qonversion SDK. The SDK handles screen **display**, **product data**, **analytics,** and **purchase tracking.**

You only need to install it once — then you can display and update No-Code screens anytime, without additional code changes.

<Info>
  On Android the No-Codes SDK is distributed as a separate package, but it includes the Qonversion SDK as a dependency.

  For iOS and other supported cross-platform frameworks, No-Codes SDK comes with the Qonversion SDK. If you already use Qonversion SDK, then simply upgrade it to the minimal required version, described below. If not, add the latest version to your project following this guide.
</Info>

***

### Supported platforms

| Platform         | SDK Version     |
| ---------------- | --------------- |
| iOS              | 6.0.0+          |
| Android          | No-Codes 1.0.0+ |
| React Native     | 10.0.0+         |
| Flutter SDK      | 11.0.0+         |
| Unity SDK        | 9.0.0+          |
| Cordova Plugin   | 7.0.0+          |
| Capacitor Plugin | 1.0.0+          |

***

## 1. Install SDKs

### Install iOS SDK

#### iOS (Swift Package Manager)

Open Xcode, go to **File → Add Package Dependencies...** (Xcode 15+; on Xcode 11-14 use **File → Swift Packages → Add Package Dependency...**), and paste `https://github.com/qonversion/qonversion-ios-sdk` into the search bar to import the package.

#### Or using CocoaPods:

Add dependency to `Podfile`.

<CodeGroup>
  ```text Podfile theme={null}
  pod 'Qonversion'
  ```
</CodeGroup>

Run `pod install` in the project directory to download the dependency.

<CodeGroup>
  ```text Podfile theme={null}
  pod install
  ```
</CodeGroup>

### Install Android SDK

Add Qonversion dependency to your package level `build.gradle` file.

<CodeGroup>
  ```groovy build.gradle theme={null}
  implementation 'io.qonversion:no-codes:1.+'
  ```
</CodeGroup>

<Warning>
  ### Migrating to the latest Qonversion SDK version

  If you are utilizing our subscription management and analytics SDK (`io.qonversion.android.sdk:sdk`), please be aware that the No-Codes SDK includes the latest version of the Qonversion SDK. Therefore, you need to manage the migration from previous major versions to the latest ones. Our migration guides located in the relevant documentation section will assist you with this process.

  After that you can remove the Qonversion SDK dependency from your `build.gradle` file and leave only the No-Codes SDK dependency there.
</Warning>

### Install React Native SDK

Install via npm or Yarn:

<CodeGroup>
  ```bash Terminal theme={null}
  npm install @qonversion/react-native-sdk --save
  ```
</CodeGroup>

<CodeGroup>
  ```bash Terminal theme={null}
  yarn add @qonversion/react-native-sdk
  ```
</CodeGroup>

After installation, make sure to install the iOS pods:

<CodeGroup>
  ```bash Terminal theme={null}
  cd ios && pod install
  ```
</CodeGroup>

### Install Flutter SDK

To use Qonversion in your Flutter app, add qonversion as a dependency in your pubspec.yaml file:

<CodeGroup>
  ```yaml pubspec.yaml theme={null}
  dependencies:
    qonversion_flutter: ^11.0.0
  ```
</CodeGroup>

Then install the dependency

<CodeGroup>
  ```text Terminal theme={null}
  flutter pub get
  ```
</CodeGroup>

After installation, make sure to install the iOS pods:

<CodeGroup>
  ```bash Terminal theme={null}
  cd ios && pod install
  ```
</CodeGroup>

### Install Unity SDK

Follow the steps described [here](unity-sdk).

### Install Cordova Plugin

Install via npm or Yarn:

<CodeGroup>
  ```bash Terminal theme={null}
  npm install @qonversion/cordova-plugin --save
  ```
</CodeGroup>

<CodeGroup>
  ```bash Terminal theme={null}
  yarn add @qonversion/cordova-plugin
  ```
</CodeGroup>

After installation, make sure to install the iOS pods:

<CodeGroup>
  ```bash Terminal theme={null}
  cd ios && pod install
  ```
</CodeGroup>

### Install Capacitor Plugin

Install via npm or Yarn:

<CodeGroup>
  ```bash Terminal theme={null}
  npm install @qonversion/capacitor-plugin --save
  ```
</CodeGroup>

<CodeGroup>
  ```bash Terminal theme={null}
  yarn add @qonversion/capacitor-plugin
  ```
</CodeGroup>

After installation, make sure to install the iOS pods:

<CodeGroup>
  ```bash Terminal theme={null}
  cd ios && pod install
  ```
</CodeGroup>

***

## 2. Get Your Project Key

1. Go to **Qonversion Dashboard** → **Settings** → **General** Tab.
2. Copy your **Project Key**.
3. Use this key in your SDK initialization.

This key connects your app to the correct project, enabling the Builder to display published screens and track metrics.

***

## 3. Initialize SDK

<CodeGroup>
  ```swift Swift theme={null}
  // You can initialize using only project key
  let configuration = NoCodesConfiguration(projectKey: "projectKey")
  NoCodes.initialize(with: configuration)
  ```

  ```kotlin Kotlin theme={null}
  // You can initialize using only project key
  val noCodesConfig = NoCodesConfig.Builder(this, "projectKey").build()
  NoCodes.initialize(noCodesConfig)
  ```

  ```java Java theme={null}
  // You can initialize using only project key
  final NoCodesConfig noCodesConfig = new NoCodesConfig.Builder(this, "projectKey").build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```typescript React Native theme={null}
  // You can initialize using only project key
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```dart Flutter theme={null}
  final noCodesConfig = new NoCodesConfigBuilder(projectKey).build();
  NoCodes.initialize(noCodesConfig);
  ```

  ```typescript Cordova theme={null}
  // You can initialize using only project key
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder('projectKey')
    .build();
  Qonversion.NoCodes.initialize(noCodesConfig);
  ```

  ```typescript Capacitor theme={null}
  // You can initialize using only project key
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .build();
  NoCodes.initialize(noCodesConfig);
  ```
</CodeGroup>

***

## What’s Next

After the SDK is connected, you can:

* [Create your first No-Code Screen](getting-started)
* [Display screens in your app](displaying-no-codes)
* [Set up fallback screens](fallbacks)

***

[Qonversion No-Code Builder](no-codes)

[Product Setup & Store Connection](product-setup-store-connection-1)


# Integrations
Source: https://documentation.qonversion.io/docs/integrations-overview

Send your in-app subscription data to destinations like AppsFlyer, Amplitude, and other major mobile platforms.

Qonversion sends subscription events, including purchases, subscriptions after free trials, renewals, refunds, and others to the integrated partners. This allows you to power your marketing and attribution platforms, as well as product analytics and retention tools, with accurate in-app subscription data.

Qonversion validates user receipts directly with app stores and tracks in-app revenue even if a user doesn't open your app. This allows you to have accurate subscription data of each subscription plan with 100% accuracy.

See the list of the events Qonversion tracks and sends to the integrated partners below.

## Tracked Events

The following section describes each event type Qonversion tracks and sends to third-party services.

| Event name                   | Description                                                                                                                                                              | Has Value by default                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Trial Started                | A user starts a trial.                                                                                                                                                   |                                                                                     |
| Trial Converted              | A trial converts to a regular auto-renewable subscription.                                                                                                               | Yes                                                                                 |
| Trial Canceled               | A trial is canceled. Cancellation can occur when a subscriber turns off auto-renew.                                                                                      |                                                                                     |
| Trial Billing Retry          | A trial went to a billing retry state. It happens if the App Store was not able to charge a user for any reason.                                                         |                                                                                     |
| Trial Still Active           | A user did not cancel the trial two days after the trial started. Sent in real time and useful for marketing optimization. (Canonical event name: `trial_still_active`.) |                                                                                     |
| Subscription Started         | A user started a subscription (only for subscriptions without a trial).                                                                                                  | Yes                                                                                 |
| Subscription Renewed         | A subscription was renewed.                                                                                                                                              | Yes                                                                                 |
| Subscription Upgraded        | A user purchases a subscription that offers a higher level of service than their current subscription.                                                                   | Yes Refunded value, if the store processes the upgrade via refund and charge again. |
| Subscription Refunded        | A user receives a refund for his previously made purchase.                                                                                                               | Yes                                                                                 |
| Subscription Canceled        | A user turns off auto-renew, or when the App Store can not charge a customer in a billing retry state.                                                                   |                                                                                     |
| Subscription Billing Retry   | A Subscription went to a billing retry state.                                                                                                                            |                                                                                     |
| In-App Purchase              | An in-app purchase occurred.                                                                                                                                             | Yes                                                                                 |
| Trial Expired                | A trial period ended and a trial lapsed (auto-renew was previously disabled by a user).                                                                                  |                                                                                     |
| Subscription Expired         | A subscription period ended and a subscription lapsed (auto-renew was previously disabled by a user).                                                                    |                                                                                     |
| Subscription Product Changed | Active subscription product has changed due to upgrade, downgrade or crossgrade.                                                                                         |                                                                                     |
| In-App Refunded              | A user receives a refund for his previously made an in-app purchase.                                                                                                     | Yes                                                                                 |

<Info>
  Qonversion sends revenue value for some events. Refund values are negative. You can finely manage the sending of revenue for any event in the Integration settings (see below).
</Info>

## Switching between subscriptions

Qonversion sends a 'Subscription Renewed' event in case of an upgrade, downgrade, or cross-grade of a subscription when a subscriber switches from his other subscription. Qonversion sends a 'Trial Converted' event if a user switches subscription and enters paid period at the same time.

Qonversion does not send downgrade event to integrations to avoid any possible data discrepancies. Both upgrade and downgrade events are shown in Qonversion in user's timeline available from the [Customers dashboard](https://dash.qonversion.io/customers).

You can check our detailed article on subscription service level and groups [here](https://qonversion.io/blog/ios-subscription-upgrades-downgrades-and-service-levels/).

## Configure Integrations

<Frame>
  <img />
</Frame>

**Each integration has the following settings, that affect all events sent in this integration:\&#xA;**

* **Send revenue properties** If you turn this toggle off, you will not receive any revenue values for this integration. We recommend to send values, so do not turn it off unless you don't need Qonversion to send revenue values. You can enable or disable sending revenue for each event.

* **Send sales as proceed** Choose if you want to send revenue values net of App Stores commission (default) or gross (before deducting App Stores commission) by switching the "Send sales as proceed" toggle.

* **Send sandbox events** Turn on the "Send sandbox events" toggle if you want to receive sandbox events from Qonversion to this integration while testing it.

**Fine-tune each event:**

* **Enable event** Turn off sending the event if you don't need it in this integration.

* **Send Revenue** Enable or disable sending revenue value for the event.

## Storefront

Integration events for Apple purchases include a `storefront` field when an App Store Connect API Certificate is configured for the Apple application in the project. The field contains the Apple App Store country code in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format (e.g. "USA", "GBR", "CHN"). This represents the App Store storefront from which the transaction originated and is not the same as the user's geographic location or the `country` field, which is based on the user's IP address.

## Event time

Qonversion can set the exact time when an event occurs for most of the events. For example, when the App Store or Google play received a payment from a user. But some events do not have the exact time. The event time for such events is set equal to the time when Qonversion detected the event while checking a user receipt. Here is the list of such events:

* Trial Canceled
* Trial Billing Retry
* Subscription Canceled
* Subscription Billing Retry
* Trial Still Active

Events are sent to integrations if tracked no later than **5 days** from the moment they appeared on App Store or Google Play. If Qonversion detects an event later than five days after it originally appeared in Apple or Google, such an event will not be sent into integrations. **Trial Still Active** events are created in Qonversion and sent in real-time. **Subscription Refunded** events are sent into integrations if tracked not later than **30 days** compared to the date available in user receipt on Apple or Google.

## Event state

Event lifecycle includes several states in Qonversion. The available event states are:

* New
* In progress
* Disabled
* Stale
* Tracked

The **New** state is assigned to an event when Qonversion initially detects it. An event can be in this state for a few seconds before Qonversion processes it further.

When the system starts processing the event, the state changes to **In progress**. The event eventually is assigned one of the three final states after processing: Disabled, Staled, Tracked. The final state depends on the event's actual time (when the event happened on the app stores) and period of relevance for events.

**Disabled** state means that the time of relevance for this event has expired. For example, Qonversion detects trial\_started event that happened a few months ago before releasing the application with Qonversion SDK. This event gets Disabled state and is not sent to your project's active integrations.

***

## Available Integrations

<CardGroup>
  <Card title="Adjust" icon="chart-mixed" href="/docs/adjust">
    Mobile measurement partner
  </Card>

  <Card title="Amazon S3" icon="bucket" href="/docs/amazon-s3">
    Raw data export to S3
  </Card>

  <Card title="Amplitude" icon="chart-line" href="/docs/amplitude">
    Product analytics
  </Card>

  <Card title="AppMetrica" icon="mobile" href="/docs/appmetrica">
    App analytics by Yandex
  </Card>

  <Card title="AppsFlyer" icon="bullseye" href="/docs/appsflyer">
    Attribution and analytics
  </Card>

  <Card title="Asapty" icon="magnifying-glass-dollar" href="/docs/asapty">
    Apple Search Ads optimization
  </Card>

  <Card title="Branch" icon="code-branch" href="/docs/branch">
    Deep linking and attribution
  </Card>

  <Card title="Braze" icon="bell" href="/docs/braze">
    Customer engagement
  </Card>

  <Card title="CleverTap" icon="user-group" href="/docs/clevertap">
    Retention and engagement
  </Card>

  <Card title="Facebook Ads" icon="rectangle-ad" href="/docs/facebook">
    Ad attribution
  </Card>

  <Card title="Firebase" icon="fire" href="/docs/firebase">
    Google analytics and events
  </Card>

  <Card title="Google Ads" icon="rectangle-ad" href="/docs/google-ads">
    Ad attribution
  </Card>

  <Card title="Google Cloud Storage" icon="cloud" href="/docs/google-cloud-storage">
    Raw data export to GCS
  </Card>

  <Card title="Kochava" icon="chart-mixed" href="/docs/kochava">
    Attribution analytics
  </Card>

  <Card title="Mailchimp" icon="envelope" href="/docs/mailchimp">
    Email marketing
  </Card>

  <Card title="Mixpanel" icon="chart-pie" href="/docs/mixpanel">
    Product analytics
  </Card>

  <Card title="OneSignal" icon="bell" href="/docs/onesignal">
    Push notifications
  </Card>

  <Card title="PostHog" icon="chart-column" href="/docs/posthog">
    Product analytics
  </Card>

  <Card title="Pushwoosh" icon="paper-plane" href="/docs/pushwoosh">
    Push notifications
  </Card>

  <Card title="SplitMetrics Acquire" icon="arrows-split-up-and-left" href="/docs/splitmetrics">
    Apple Search Ads
  </Card>

  <Card title="Segment" icon="diagram-project" href="/docs/segment">
    Customer data platform
  </Card>

  <Card title="Singular" icon="chart-mixed" href="/docs/singular">
    Marketing analytics
  </Card>

  <Card title="Slack" icon="hashtag" href="/docs/slack">
    Team notifications
  </Card>

  <Card title="Tenjin" icon="chart-line" href="/docs/tenjin">
    Ad revenue analytics
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/webhooks">
    Custom HTTP endpoints
  </Card>
</CardGroup>


# iOS 3.+ migration guide
Source: https://documentation.qonversion.io/docs/ios-3-migration-guide

Historical migration guide for upgrading the Qonversion iOS SDK to major version 3.+: updated initialization, renamed methods, and revised purchase and entitlement APIs.

## Initialization

Qonversion iOS SDK 3 contains significant changes in how the library is initialized. Before, you initialized Qonversion using the `launch` call:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.launch(withKey: "projectKey")
  ```

  ```objectivec Objective-C theme={null}
  [Qonversion launchWithKey:@"projectKey"];
  ```
</CodeGroup>

Now, instead, you should create a Qonversion Configuration object and provide it to the initialization method as follows:

<CodeGroup>
  ```swift Swift theme={null}
  let configuration = Qonversion.Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
  Qonversion.initWithConfig(configuration)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
  [Qonversion initWithConfig:configuration];
  ```
</CodeGroup>

Note that now you should provide a concrete value from the `Qonversion.LaunchMode` enum, depending on which mode you use Qonversion. Also, we've renamed our modes to make them clearer for users:

* "Observe" mode becomes [Analytics mode](analytics-mode),
* "Infrastructure" mode becomes [Subscription Management mode](subscription-management-mode).

After the initialization, you can access the Qonversion instance whenever you want as follows:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared()
  ```

  ```objectivec Objective-C theme={null}
  [Qonversion sharedInstance];
  ```
</CodeGroup>

So you should replace all your Qonversion calls with the construction above.

Also, if you were using `Qonversion.setDebugMode()` for testing purposes, you should now call the `setEnvironment(.sandbox)` method of the `Qonversion Config before calling Qonversion.initWithConfig()`.

<CodeGroup>
  ```swift Swift theme={null}
  let configuration = Qonversion.Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
  configuration.setEnvironment(.sandbox)
  Qonversion.initWithConfig(configuration)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
  [configuration setEnvironment:QONEnvironmentSandbox];
  [Qonversion initWithConfig:configuration];
  ```
</CodeGroup>

As no `launch` method is available anymore, you won't get `QNLaunchResult` as a result. The good news is that there are analogues for all the fields you might have been using from there:

* for `uid`, call `userInfo()` and get the `qonversionId` field of the `Qonversion.User` object from the result,
* for `products` call `products()`,
* for `offerings` call `offerings()`,
* for `permissions`, call `checkEntitlements()`.

## Entitlements

We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

| Version \<3                             | Version 3+                               |
| --------------------------------------- | ---------------------------------------- |
| Qonversion.Permission                   | Qonversion.Entitlement                   |
| Qonversion.PermissionsCompletionHandler | Qonversion.EntitlementsCompletionHandler |
| Qonversion.PermissionRenewState         | Qonversion.EntitlementRenewState         |
| Qonversion.PermissionSource             | Qonversion.EntitlementSource             |
| Qonversion.PermissionsCacheLifetime     | Qonversion.EntitlementsCacheLifetime     |
| Qonversion.checkPermissions()           | Qonversion.checkEntitlements()           |
| UpdatedPurchasesListener                | Qonversion.EntitlementsUpdateListener    |

The `Qonversion.Entitlement` class contains the same information as the `Qonversion.Permission` with minor renaming.

* `permissionID` was renamed to `entitlementID`,

There is no `setUpdatedPurchasesListener` method in Qonversion. You should provide `UpdatedEntitlementsListener` to `Qonversion.Configuration` during the initialization using the `setEntitlementsUpdateListener` method. The exact change is made to the `setPermissionsCacheLifetime` method. Now you can set the required lifetime using the `Qonversion.Configuration` `setEntitlementsCacheLifetime` function while Qonversion initialization.

<CodeGroup>
  ```swift Swift theme={null}
  let configuration = Qonversion.Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
  configuration.setEntitlementsUpdateListener(self)
  Qonversion.initWithConfig(config)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
  [configuration setEntitlementsCacheLifetime:QONEntitlementsCacheLifetimeThreeMonths];
  [Qonversion initWithConfig:configuration];
  ```
</CodeGroup>

## Automation changes

We've also changed the way the `Automations` is used. As in Qonversion, you should use `Automations` via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.

<Warning>
  You should access the shared instance of `Automations` strictly after you initialize Qonversion.
</Warning>

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.initWithConfig(...)
  Qonversion.Automations.shared().setDelegate(...)
  ```

  ```objectivec Objective-C theme={null}
  [Qonversion initWithConfig:...];
  [[QONAutomations sharedInstance] setDelegate:...];
  ```
</CodeGroup>

Also, the methods for working with push notifications were moved from `Qonversion` to `Automations`, so if you were using the following methods:

* `setNotificationsToken`,
* `handleNotification`,
* `getNotificationCustomPayload` make sure to make calls from the Automations instance instead of the Qonversion one.

## Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

* the deprecated methods `resetUser` and `setUserId` were removed. `resetUser` was deprecated for a long time and did nothing, so there is nothing to replace this call with, remove the call if you were still using it for some reason. `setUserId` should be replaced with the `setProperty` call with `.userID` parameter.
* the `experiments` method was removed - we are now working on a new design of A/B experiments;
* the `Qonversion.AttributionSource` enum was renamed to `Qonversion.AttributionProvider`.
* the `checkTrialIntroEligibilityForProductIds` method was shortened to `checkTrialIntroEligibility`;
* added the new method `userInfo`, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
* added new enum values - `Qonversion.OfferingTag.Unknown` and `Qonversion.TrialDuration.Unknown`, which are used when parsing fails.
* all the classes and functions' namings were fixed for Swift;
* all the class prefixes were changed from `QN` to `QON` for Objective-C.

***

[\[Dec 2022\] Migration Guide](migrate-to-the-actual-qonversion-sdk-version-december-2022)

[Android 4.+ migration guide](android-4-migration-guide)


# iOS 5.+ migration guide
Source: https://documentation.qonversion.io/docs/ios-5-migration-guide

Historical migration guide for upgrading the Qonversion iOS SDK to major version 5.+: renamed entities and methods with a before/after reference for updating your integration.

## Renamings

In this major version, we have renamed several entities and public methods to make our namings more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade                                | After upgrade                                               |
| --------------------------------------------- | ----------------------------------------------------------- |
| `QONProperty` (swift - `Qonversion.Property`) | `QONUserPropertyKey` (swift - `Qonversion.UserPropertyKey`) |
| `setUserProperty`                             | `setCustomUserProperty`                                     |
| `setProperty`                                 | `setUserProperty`                                           |

## User properties changes

In addition to the above renamings we have added a new class `QONUserProperty`, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().userProperties({ userProperties, error in
    if let error = error {
      // Handle error
      return
    }
    
    userProperties?.properties.forEach({ userProperty in
      print("User property: ", "key: ", userProperty.key, ", value: ", userProperty.value)
    })
  });
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] userProperties:^(QONUserProperties * _Nullable userProperties, NSError * _Nullable error) {
    if (error) {
      // Handle error
      return;
    }

    [userProperties.properties enumerateObjectsUsingBlock:^(QONUserProperty * _Nonnull userProperty, NSUInteger idx, BOOL * _Nonnull stop) {
      NSLog(@"User property: key: %@, value: %@", userProperty.key, userProperty.value);
    }];
  }];
  ```
</CodeGroup>

`QONUserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method                  | Arguments                    | Description                                                                                              |
| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `propertyForKey`        | `key` - string               | Searches for a property with the given property `key` in all properties list                             |
| `definedPropertyForKey` | `key` - `QONUserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `QONUserPropertyKey` enum with several values:

* added new property keys `FacebookAttribution` and `AppSetId`, which is used on Android but can be received on iOS due to cross-platform user management;
* added a `Custom` key to represent all the custom properties.

***

[\[Aug 2023\] Migration Guide](qonversion-sdk-major-version)

[Android 6.+ migration guide](android-6-migration-guide)


# iOS App Extensions
Source: https://documentation.qonversion.io/docs/ios-app-extensions

Learn how to enable data sharing in Qonversion for Apple App Extensions.

[App Extensions](https://developer.apple.com/app-extensions/) in Apple operating systems are important features that let you extend custom functionality and content beyond your app and make it available to users while they’re interacting with other apps or the system. Qonversion also supports this feature.

[Understand How an App Extension Works](https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionOverview.html#//apple_ref/doc/uid/TP40014214-CH2-SW2)

## Configuring the App

First, you need to enable data sharing between your app and shared extensions.

1. [Enable app groups](https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionScenarios.html#//apple_ref/doc/uid/TP40014214-CH21-SW1) for the containing app and extension via Xcode or the Developer portal. Choose your App target in Xcode. Select `Signing & Capabilities`, click `+ Capability` and select `App Groups`.
2. [Register the app group](https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW19) in the portal. In Xcode, add the new App Group ID.
3. Choose that App Group ID for the extension and containing app.
4. Pass user defaults instance created with a suite name to Qonversion via Qonversion.Configuration `setCustomUserDefaults()` function.

<CodeGroup>
  ```swift Swift theme={null}
  let config = Qonversion.Configuration(projectKey: "project_key", launchMode: .subscriptionManagement)
  ...
  // any other configurations
  ...
  config.setCustomUserDefaults(.init(suiteName: "app_groups_id_from_previous_step"))
  Qonversion.initWithConfig(config)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"project_key" launchMode:QONLaunchModeSubscriptionManagement];
  ...
  // any other configurations
  ...
  [configuration setCustomUserDefaults:[[NSUserDefaults alloc] initWithSuiteName:@"app_groups_id_from_previous_step"]];
  [Qonversion initWithConfig:configuration];
  ```
</CodeGroup>

After those steps, all content stored in the user defaults will be shared between the shared extension and containing App.

***

[macOS / Catalyst](macos-catalyst)

[Kids Mode](kids-mode-sdk)


# iOS App-Specific Shared Secret
Source: https://documentation.qonversion.io/docs/ios-app-specific-shared-secret

Generate and obtain your app-specific shared secret from App Store Connect to enable Qonversion receipt validation for iOS subscriptions.

**iOS App-Specific Shared Secret**

App-Specific Shared Secret is a key to receiving receipts for auto-renewable in-app subscriptions.\
You need to provide the Shared Secret to Qonversion so that we can verify your in-app purchases. Follow the steps below to get the Shared Secret for your iOS app:

1. <a href="https://appstoreconnect.apple.com/login">Log in</a> to your App Store Connect account.
2. Choose <a href="https://appstoreconnect.apple.com/apps">Apps</a>
3. Select the App Information section from the left side menu.
4. Scroll down to the "App-Specific Shared Secret" label and click the "Manage" button.
5. Generate and copy your shared secret.

<a href="/docs/ios-app-store-info-fields#2-generate-the-app-specific-shared-secret">Open docs</a>


# iOS App Store Info Fields
Source: https://documentation.qonversion.io/docs/ios-app-store-info-fields

How to find your Bundle ID, App Store ID, and App-Specific Shared Secret in App Store Connect — the three required fields for connecting your iOS app to Qonversion.

The Core setup step in the Qonversion iOS configuration wizard asks for three identifiers that Apple uses to recognize your app and authorize receipt validation:

* **Bundle ID** — the reverse-DNS identifier of the app (e.g. `com.example.app`).
* **App Store ID** — the numeric ID Apple assigns to a published app (e.g. `1234567890`).
* **App-Specific Shared Secret** — a 32-character secret used to validate auto-renewable subscription receipts.

All three live on the **App Information** screen of a single app in App Store Connect, so you can grab them in one trip.

## 1. Copy the Bundle ID and App Store ID

1. [Log in](https://appstoreconnect.apple.com/login) to App Store Connect.
2. Open **My Apps**, click your app, and choose **App Information** in the left sidebar.
3. Under **General Information**, copy:
   * **Bundle ID** (looks like `com.example.app`) — paste into Qonversion's **Bundle ID** field.
   * **Apple ID** (numeric, e.g. `1234567890`) — this is what Qonversion calls the **App Store ID**.

<Tip>
  You can also read the App Store ID from the URL bar while the app is open: `https://appstoreconnect.apple.com/apps/<APP_STORE_ID>/...`
</Tip>

<Frame>
  <img />
</Frame>

## 2. Generate the App-Specific Shared Secret

Still on **App Information**, scroll down to the **App-Specific Shared Secret** card and click **Manage**. In the dialog that opens, click **Generate** if you don't have one yet, then copy the 32-character secret.

<Frame>
  <img />
</Frame>

<Note>
  An app-specific shared secret is per-app and stays the same once generated. You can revoke and regenerate it from this dialog at any time, but doing so invalidates the previous value everywhere it's used.
</Note>

## 3. Paste everything into Qonversion

1. Open Qonversion Dash → **Project Settings** → **Stores** → **Apple App Store**.
2. On **Step 2 · Core setup**:
   * Paste the **App-Specific Shared Secret**.
   * Paste the **Bundle ID**.
   * Paste the **App Store ID**.

<Tip>
  If you completed Step 1 (App Store Connect API key) and verified your credentials, Bundle ID and App Store ID may already be auto-filled — pick the app from the dropdown to fill them in. You can still edit either field by hand afterwards.
</Tip>

## Troubleshooting

### "App Store ID is invalid"

The App Store ID is purely numeric — usually 9 to 10 digits. If you accidentally copied something with letters or punctuation (the bundle id, for example), Qonversion will reject it. Double-check the **Apple ID** field on App Information, not the Bundle ID.

### "App-Specific Shared Secret is invalid"

The shared secret is exactly 32 characters, hex-style. If pasting from a manager that adds spaces, trim them; if you generated a Master Shared Secret instead (in **Users and Access → Integrations**), that's a different value and won't work for per-app receipt validation.

### Bundle ID doesn't match the one in your Xcode project

Apple ties the bundle id to the app record on App Store Connect; you can't change it after submission. Make sure the value you paste here matches the **Bundle Identifier** in your Xcode target's signing settings — they have to be identical for receipt validation to succeed.

***

## What's next?

After this step, finish the rest of the wizard:

* **Step 3 · Server API access** — generate an [In-App Purchase API Key](apple-promotional-offers) and upload it.
* **Step 4 · Production readiness** — copy the [Server-to-Server Notification URL](ios-s2s-notifications) into App Store Connect.


# Apple Server-to-Server Notifications
Source: https://documentation.qonversion.io/docs/ios-s2s-notifications

How to forward Apple's server-to-server notifications to Qonversion so renewal, refund and subscription-status events arrive in real time.

Apple sends a notification to a URL of your choice every time a subscription event happens on your app — renewals, refunds, billing retries, status changes. Qonversion exposes one URL per project; pasting it into App Store Connect is a one-time setup.

<Note>
  Without S2S notifications, Qonversion still detects events by polling Apple, but updates land minutes to hours late and analytics quality degrades. The wizard surfaces the URL on Step 4 specifically because of this — production environments should always have S2S enabled.
</Note>

## 1. Copy the URL from Qonversion

The Apple Server-to-Server Notification URL is available in two places — grab it from whichever is closer to where you are:

* **Project Settings → Stores → Apple App Store** card. Once your iOS store is configured, the URL appears at the bottom of the platform card with a copy icon next to it. Open this any time after the initial setup.
* **Step 4 · Production readiness** of the iOS configuration wizard, in the **Apple Server-to-Server Notification URL** field. Most natural during first-time setup.

The URL looks like `https://api.qonversion.io/v1/apple-s2s/<your-project-key>`. Click the copy icon next to it.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

## 2. Paste into App Store Connect

1. [Log in](https://appstoreconnect.apple.com/login) to App Store Connect.
2. Open **My Apps**, click your app, then choose **App Information** in the left sidebar.
3. Scroll to the **App Store Server Notifications** section.
4. Paste the URL into the **Production Server URL** field.
5. Choose **Version 2** for the Server Notifications version (Version 1 is legacy).
6. Click **Save** at the top of the page.

<Frame>
  <img />
</Frame>

<Tip>
  If you also test in the App Store sandbox, paste the same URL into the **Sandbox Server URL** field — Qonversion accepts both production and sandbox notifications on the same endpoint.
</Tip>

## Troubleshooting

### Apple shows "Could not verify your URL"

App Store Connect probes the URL when you save. The probe expects an HTTP 200 response within a few seconds. If you see this error:

* Make sure you copied the full URL including `https://` and the project key.
* Make sure you're not behind a corporate proxy that's rewriting outbound requests.
* Try saving again after a minute — Apple's probe occasionally times out on transient network blips.

### Notifications aren't appearing in Qonversion analytics

* Check that you saved with **Version 2** selected. Qonversion supports both, but Version 2 carries a richer payload.
* Verify the URL points to the **same project** you're configuring in Qonversion — projects don't share keys.
* Wait 10-15 minutes after the first eligible event (renewal, refund, etc.) — Apple batches some notification types.

***

## What's next?

After this step, your iOS configuration is complete. Test the integration end-to-end:

* Make a sandbox purchase and confirm it appears in Qonversion within seconds (not minutes).
* Trigger a refund in App Store Connect and confirm the refund event arrives.


# iOS
Source: https://documentation.qonversion.io/docs/ios-sdk-setup

Install Qonversion iOS SDK to implement in-app subscriptions, validate user receipts, get subscription analytics, and send subscription events to third-party integrations.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/qonversion-ios-sdk?label=Latest%20Release)](https://github.com/qonversion/qonversion-ios-sdk/releases)

## Install SDK

Qonversion supports Cocoapods, Carthage, and Swift Package Manager to package your dependencies as a framework.

## Install via Cocoapods

Add dependency to `Podfile`.

<CodeGroup>
  ```text Podfile theme={null}
  pod 'Qonversion'
  ```
</CodeGroup>

Run `pod install` in the project directory to download the dependency.

<CodeGroup>
  ```bash Terminal theme={null}
  pod install
  ```
</CodeGroup>

## Install via Carthage

To integrate SDK into your Xcode project using Carthage, specify it in your Cartfile:

<CodeGroup>
  ```text Cartfile theme={null}
  github "qonversion/qonversion-ios-sdk"
  ```
</CodeGroup>

After that, run the Carthage update to build the framework and drag the built Qonversion.framework into your Xcode project.

<CodeGroup>
  ```bash Terminal theme={null}
  carthage update
  ```
</CodeGroup>

## Install via Apple Swift Package Manager

Open Xcode, go to **File → App packages...** and enter the package URL `https://github.com/qonversion/qonversion-ios-sdk` to the search bar to import the package.

## Kids Mode for Qonversion IOS SDK

In case you are building an App for Kids, please, [follow this guide](kids-mode-sdk) to learn more about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# [Jul 2024] Migration guide. Google Play Billing Library 7.
Source: https://documentation.qonversion.io/docs/jan-2024-migration-guide-google-play-billing-library-6-copy

We have released a major update to our Android and cross-platform Qonversion SDKs with new Google Play Billing Library support and several improvements. This article enumerates the steps necessary to migrate from previous SDK versions to the ones displayed in the table below:

| Platform     | Major version |
| ------------ | ------------- |
| Android      | 8.x           |
| Flutter      | 9.x           |
| React Native | 8.x           |
| Unity        | 8.x           |
| Cordova      | 6.x           |

Choose your platform to continue:

* [Android SDK 7.x to 8.x migration guide](android-8-migration-guide)
* [Flutter SDK 8.x to 9.x migration guide](flutter-9-migration-guide)
* [React Native SDK 7.x to 8.x migration guide](react-native-8-migration-guide)
* [Unity SDK 7.x to 8.x migration guide](unity-8-migration-guide)
* [Cordova SDK 5.x to 6.x migration guide](cordova-6-migration-guide)

<Info>
  ### More Resources in Our Blog
</Info>

* [Google Play Billing Library 7](https://qonversion.io/blog/google-play-billing-7/)
* [Google Play I/O 2024 Updates](https://qonversion.io/blog/google-play-i-o-2024-updates-for-app-developers/)

***

[\[July 2025\] Migration guide. Google Play Billing Library 8.](july-2025-migration-guide-google-play-billing-library-8)

[Android SDK 7.x to 8.x migration guide](android-8-migration-guide)


# [Jan 2026] Migration guide. Capacitor 1.
Source: https://documentation.qonversion.io/docs/jan-2026-migration-guide-capacitor-1

In this major release of the Qonversion Capacitor Plugin, we've made crucial changes to support No-Codes along with the new purchase method, plugin migration to the Qonversion organization in NPM, and some others.

## No-Codes support

Qonversion No-Codes are now officially released! For integration steps, please follow our [documentation](no-codes).

## Capacitor 8 support

We are now supporting the new Capacitor 8. For that purpose, we've upgraded the minimal supported native versions:

* iOS version - 13.0 -> 14.0,
* Android version - 22 -> 23,
* Java version - 17 -> 21.

## New purchase method

We have refactored the `purchase` method - now it returns comprehensive information, including status, entitlements after the purchase, error information if it happened, and also stores transaction info. After upgrading to this version, rewrite your `purchase` calls as follows:

<CodeGroup>
  ```typescript Before theme={null}
  try {
    // Old method returned only Map<string, Entitlement>
    const entitlements = await Qonversion.getSharedInstance().purchaseProduct(product, purchaseOptions);
    
    // Check for entitlement
    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement?.isActive) {
      console.log('Purchase successful! Premium access granted.');
    }
  } catch (error) {
    // All errors, including user cancellation, were handled via catch
    if (error.code === QonversionErrorCode.CanceledPurchase) {
      console.log('User canceled the purchase');
    } else {
      console.error('Purchase failed:', error.message);
    }
  }
  ```

  ```typescript After theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);

  if (result.isSuccess) {
    // Purchase succeeded
    const premiumEntitlement = result.entitlements?.get('premium');
    if (premiumEntitlement?.isActive) {
      console.log('Purchase successful! Premium access granted.');
    }

    // Access transaction details
    console.log('Transaction ID:', result.storeTransaction?.transactionId);
    console.log('Product ID:', result.storeTransaction?.productId);

  } else if (result.isCanceled) {
    // User canceled — not an error, just a status
    console.log('User canceled the purchase');

  } else if (result.isPending) {
    // Purchase awaiting confirmation (e.g., parental controls, deferred payments)
    console.log('Purchase is pending approval');

  } else if (result.isError) {
    // An actual error occurred
    console.error('Purchase failed:', result.error?.description);
    console.error('Error code:', result.error?.code);
  }
  ```
</CodeGroup>

## Google Play Billing Library upgrade to version 8

In this version, we've upgraded Google Play Billing Library on Android to version 8.1.0, which results in `skuDetails` removal from `Product` and also requires setting up Base Plan ID for all the subscription products in the Qonversion Dashboard, if you haven't set them yet. Read more [here](july-2025-migration-guide-google-play-billing-library-8#upgrade-subscription-products-in-qonversion-dashboard).

## Properties renamings

We've made a couple of renamings of our DTO properties to sync them with the rest codestyle. If you were using these fields, simply upgrade their names as described in the table below

| Old name               | New name               |
| ---------------------- | ---------------------- |
| `Product.qonversionID` | `Product.qonversionId` |
| `Product.storeID`      | `Product.storeId`      |
| `Product.basePlanID`   | `Product.basePlanId`   |

***

[\[Jan 2026\] Migration guide. Cordova 7.](jan-2026-migration-guide-cordova-7)

[\[Nov 2025\] Migration guide. iOS 6.0.0](nov-2025-migration-guide-ios-600)


# Overview
Source: https://documentation.qonversion.io/docs/jan-2026-migration-guide-cordova-7

In this major release of the Qonversion Cordova Plugin, we've made crucial changes to support No-Codes along with the new purchase method, plugin migration to the Qonversion organization in NPM, and some others.

## No-Codes support

Qonversion No-Codes are now officially released! For integration steps, please follow our [documentation](no-codes).

## Automation removal

We have switched from the Automations support to the new No-Codes Builder, so all the Automations methods were completely removed. Please, consider migrating to the new No-Codes - they are very simple and much more functional!

## Upgrading library

We've migrated the library to the Qonversion organization in NPM, so along with the version update, you should also change the name of the library and all the imports.

In your *package.json* file, upgrade the name and the version of the Qonversion SDK:

<CodeGroup>
  ```json package.json theme={null}
  // Before
  // "cordova-plugin-qonversion": "^6.0.0"

  // Now
  "@qonversion/cordova-plugin": "^7.0.0"
  ```
</CodeGroup>

## New purchase method

We have refactored the `purchase` method - now it returns comprehensive information, including status, entitlements after the purchase, error information if it happened, and also stores transaction info. After upgrading to this version, rewrite your `purchase` calls as follows:

<CodeGroup>
  ```typescript Before theme={null}
  try {
    // Old method returned only Map<string, Entitlement>
    const entitlements = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);

    // Check for entitlement
    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement?.isActive) {
      console.log('Purchase successful! Premium access granted.');
    }
  } catch (error) {
    // All errors, including user cancellation, were handled via catch
    if (error.code === Qonversion.QonversionErrorCode.PURCHASE_CANCELED) {
      console.log('User canceled the purchase');
    } else {
      console.error('Purchase failed:', error.message);
    }
  }
  ```

  ```typescript After theme={null}
  const purchaseResult = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);

  if (purchaseResult.isSuccess) {
    // Purchase succeeded
    const premiumEntitlement = purchaseResult.entitlements?.get('premium');
    if (premiumEntitlement?.isActive) {
      console.log('Purchase successful! Premium access granted.');
    }
    
    // Access transaction details
    console.log('Transaction ID:', purchaseResult.storeTransaction?.transactionId);
    
  } else if (purchaseResult.isCanceled) {
    // User canceled the purchase (not an error)
    console.log('User canceled the purchase');
    
  } else if (purchaseResult.isPending) {
    // Purchase is awaiting confirmation (e.g., parental controls)
    console.log('Purchase is pending approval');
    
  } else if (purchaseResult.isError) {
    // An error occurred
    console.error('Purchase failed:', purchaseResult.error?.description);
  }
  ```
</CodeGroup>

If you were using `updatePurchase` (for Android), migrate as follows:

<CodeGroup>
  ```typescript Before theme={null}
  try {
    // Created a special model for updates
    const purchaseUpdateModel = product.toPurchaseUpdateModel(
      oldProduct, // Current subscription product
      Qonversion.PurchaseUpdatePolicy.WITH_TIME_PRORATION  // Update policy
    );
    
    const entitlements = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
    
    const premiumEntitlement = entitlements?.get('premium');
    if (premiumEntitlement?.isActive) {
      console.log('Subscription upgraded successfully!');
    }
  } catch (error) {
    if (error.code === Qonversion.QonversionErrorCode.PURCHASE_CANCELED) {
      console.log('User canceled the upgrade');
    } else {
      console.error('Upgrade failed:', error.message);
    }
  }
  ```

  ```typescript After theme={null}
  // Use PurchaseOptionsBuilder to specify update parameters
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)                              // Current subscription product
    .setUpdatePolicy(Qonversion.PurchaseUpdatePolicy.WITH_TIME_PRORATION)  // Update policy
    .build();

  const purchaseResult = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);

  if (purchaseResult.isSuccess) {
    console.log('Subscription upgraded successfully!');
    console.log('New transaction ID:', purchaseResult.storeTransaction?.transactionId);
    
    const premiumEntitlement = purchaseResult.entitlements?.get('premium');
    if (premiumEntitlement?.isActive) {
      console.log('Premium access is now active');
    }
    
  } else if (purchaseResult.isCanceled) {
    console.log('User canceled the upgrade');
    
  } else if (purchaseResult.isPending) {
    console.log('Upgrade is pending');
    
  } else if (purchaseResult.isError) {
    console.error('Upgrade failed:', purchaseResult.error?.description);
  }
  ```
</CodeGroup>

## Google Play Billing Library upgrade to version 8

In this version, we've upgraded Google Play Billing Library on Android to version 8.1.0, which results in `skuDetails` removal from `Product` and also requires setting up Base Plan ID for all the subscription products in the Qonversion Dashboard, if you haven't set them yet. Read more [here](july-2025-migration-guide-google-play-billing-library-8#upgrade-subscription-products-in-qonversion-dashboard).

## Properties renamings

We've made a couple of renamings of our DTO properties to sync them with the rest codestyle. If you were using these fields, simply upgrade their names as described in the table below

| Old name               | New name               |
| ---------------------- | ---------------------- |
| `Product.qonversionID` | `Product.qonversionId` |
| `Product.storeID`      | `Product.storeId`      |
| `Product.basePlanID`   | `Product.basePlanId`   |

***

[Google Play Service Account Key](android-store-setup)

[\[Jan 2026\] Migration guide. Capacitor 1.](jan-2026-migration-guide-capacitor-1)


# [July 2025] Migration guide. Google Play Billing Library 8.
Source: https://documentation.qonversion.io/docs/july-2025-migration-guide-google-play-billing-library-8

Google Play has recently launched a new major version of its billing library. We have incorporated all the updates in our latest major Android SDK - version 9. This article outlines the steps required to transition from the previous SDK version to the newest one.

## Upgrading version

Increase the dependency version in your app *build.gradle* file to upgrade your Qonversion SDK to the latest version

<CodeGroup>
  ```groovy build.gradle theme={null}
  dependencies {
       implementation 'io.qonversion.android.sdk:sdk:9.+'
  }
  ```
</CodeGroup>

## Deprecated purchase methods with `QPurchaseModel` were removed

We have been using various `purchase` methods with different signatures for quite some time, and since some of them have been deprecated, we have decided to remove them in this release.

If your code relies on these methods, please take the time to upgrade to the newer methods as outlined below.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  // Old
  Qonversion.shared.purchase(activity, product.toPurchaseModel(), callback)

  Qonversion.shared.purchase(activity, product.toPurchaseModel(offerId), callback)

  Qonversion.shared.purchase(activity, product.toPurchaseUpdateModel(oldProductId, updatePolicy), callback)

  // New
  Qonversion.shared.purchase(activity, product, callback)

  val options = QPurchaseOptions.Builder()
      .setOfferId(offerId)
      .build()
  Qonversion.shared.purchase(activity, product, options, callback)

  val options = QPurchaseOptions.Builder()
      .setOldProduct(oldProduct)
      .setUpdatePolicy(updatePolicy)
      .build()
  Qonversion.shared.purchase(activity, product, options, callback)
  ```

  ```java Java theme={null}
  // Old
  Qonversion.getSharedInstance().purchase(activity, product.toPurchaseModel(), callback);

  Qonversion.getSharedInstance().purchase(activity, product.toPurchaseModel(offerId), callback);

  Qonversion.getSharedInstance().purchase(activity, product.toPurchaseUpdateModel(oldProductId, updatePolicy), callback);

  // New
  Qonversion.getSharedInstance().purchase(activity, product, callback)

  QPurchaseOptions options = new QPurchaseOptions.Builder()
      .setOfferId(offerId)
      .build();
  Qonversion.getSharedInstance().purchase(activity, product, options, callback);

  QPurchaseOptions options = new QPurchaseOptions.Builder()
      .setOldProduct(oldProduct)
      .setUpdatePolicy(updatePolicy)
      .build();
  Qonversion.getSharedInstance().purchase(activity, product, options, callback);
  ```
</CodeGroup>

## The deprecated field `QProduct.skuDetail` was removed

Google has eliminated the ways to query deprecated `SkuDetails` for products, having transitioned to `ProductDetails`. We are keeping up with these updates and removing the `skuDetail` field from the `QProduct` class. Each `skuDetail` field has a corresponding entry in `QProduct.storeDetails`, so please consider migrating to the updated structure.

Additionally, if you haven't done so already, please specify the base plan ID for subscription products in the Qonversion dashboard. Further details can be found in the next section.

## Upgrade subscription products in Qonversion Dashboard

Google Billing has eliminated deprecated methods related to `SkuDetails`, which were previously utilized to ascertain store details and facilitate product sales solely using their product ID. Following the product structure overhaul in Google Play Billing Library 6, Google introduced various base plans for the same subscription product. `SkuDetails` remained responsible for managing store details for the sole backwards-compatible base plan of the product.

Consequently, to achieve the same functionality with subscription products that were previously identified solely by product ID, it is now necessary to specify the backwards-compatible base plan ID in the Qonversion Dashboard.

<img alt="" />

### One-time products and purchase options

The same structure applies to one-time products, which Google Play Billing Library 8 reorganized into products, [purchase options, and offers](https://developer.android.com/google/play/billing/one-time-products). If a one-time product exposes several purchase options and you want a Qonversion product to map to a specific one, set its identifier in the **Google Play Purchase Option ID** field in the Qonversion Dashboard. Leave the field empty to keep using the product's default purchase option.

<Note>
  Selecting a specific one-time purchase option requires an Android SDK version that supports it. Older SDK versions ignore the **Purchase Option ID** and always use the product's default one-time offer. Leave the field empty unless you are on a version that supports purchase options.
</Note>

## `restore`, `syncPurchases` and `syncHistoricalData` changes

In Google Play Billing Library 8, the method for receiving historical purchases has been eliminated, and there are no alternative methods available. This indicates that fetching historical purchases, such as expired or consumed one-time products, is no longer possible.

Implications for Qonversion:

* The `syncHistoricalData` method has been deprecated, as it can't completely fulfill its purpose anymore. If you relied on this method for migrating your userbase purchases history to Qonversion, you will no longer be able to do so following this major update. For other available options, please refer to [our documentation](migrating-subscriptions).
* The `restore` and `syncPurchases` methods will now function solely with active subscriptions and non-consumed one-time purchases. This change will not impact user experience, as expired subscriptions or consumed one-time purchases did not provide any entitlements previously. However, they will also not be reflected in Qonversion analytics if they were not tracked by Qonversion earlier, as we will not receive any data on them from Google Play Billing.

## Renaming ID to Id in offerings and products

We had been dealing with inconsistencies in the spelling of ID and Id across various property and method names for quite some time. Now, we’re aligning it with Google’s approach — using Id consistently everywhere. Below is a table outlining the places where the spelling has been updated. Please consider replacing ID with Id.

| Old name                     | New name                     |
| ---------------------------- | ---------------------------- |
| `QOffering.offeringID`       | `QOffering.offeringId`       |
| `QOffering.productForID()`   | `QOffering.productForId()`   |
| `QOfferings.offeringForID()` | `QOfferings.offeringForId()` |
| `QProduct.qonversionID`      | `QProduct.qonversionId`      |
| `QProduct.storeID`           | `QProduct.storeId`           |
| `QProduct.basePlanID`        | `QProduct.basePlanId`        |
| `QProduct.offeringID`        | `QProduct.offeringId`        |

***

[\[Nov 2025\] Migration guide. React Native 10.](sep-2025-migration-guide-react-native-10)

[\[Jul 2024\] Migration guide. Google Play Billing Library 7.](jan-2024-migration-guide-google-play-billing-library-6-copy)


# Kids Mode
Source: https://documentation.qonversion.io/docs/kids-mode-sdk

Easily enable Kids Mode in Qonversion SDK to comply with Apple and Google policies. No IDFA, GAID, or ad data collected.

When you're building an app for kids, it is necessary to follow policies from [Apple](https://developer.apple.com/app-store/kids-apps/) and [Google](https://support.google.com/googleplay/android-developer/answer/9893335). To help you with it, we have implemented separate Kids Mode settings for our SDKs.

What is included: we do not collect IDFA, GAID and other advertisement attributes in case the mode is enabled.

## iOS

Kids Mode for iOS SDK is available for installation using CocoaPods. Please, follow the steps below:

1. Add dependency to your `Podfile`.

<CodeGroup>
  ```text Podfile theme={null}
  pod 'Qonversion/NoIdfa'
  ```
</CodeGroup>

2. Run `pod install` in the project directory to download the dependency.

<CodeGroup>
  ```text Terminal theme={null}
  pod install
  ```
</CodeGroup>

<Note>
  Starting from iOS SDK version 6.12.1, the `Qonversion/NoIdfa` flavor also includes [No-Codes](getting-started) — paywalls and onboarding screens built with No-Codes work in Kids Mode out of the box. On earlier SDK versions, No-Codes is not available in this flavor.
</Note>

## Android & Android-based cross-platforms

<Warning>
  ### Kids Mode for iOS - based cross-platform SDKs

  Cross-platform SDKs support Kids Mode only for the Android part. If you need a cross-platform SDK that supports Kids Mode for iOS, please get in touch with us using Intercom chat or [the following email address](mailto:hi@qonversion.io).
</Warning>

For Android & Android-based cross-platforms, you can [install our SDKs as usual](install-sdk).

Then enable Kids Mode during the initialization phase:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  import com.qonversion.android.sdk.Qonversion
  import com.qonversion.android.sdk.QonversionConfig
  import com.qonversion.android.sdk.dto.QLaunchMode

  public class App : Application() {
      override fun onCreate() {
          super.onCreate()
          val qonversionConfig = QonversionConfig.Builder(
              this,
              "projectKey",
              QLaunchMode.SubscriptionManagement
          )
           .enableKidsMode()
           .build()
          Qonversion.initialize(qonversionConfig)
      }
  }
  ```

  ```java Java theme={null}
  import com.qonversion.android.sdk.Qonversion;
  import com.qonversion.android.sdk.QonversionConfig;
  import com.qonversion.android.sdk.dto.QLaunchMode;

  public class App extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
                  this,
                  "projectKey",
                  QLaunchMode.SubscriptionManagement
          )
            .enableKidsMode()
            .build();
          Qonversion.initialize(qonversionConfig);
      }
  }
  ```

  ```dart Flutter theme={null}
  import 'package:qonversion_flutter/qonversion_flutter.dart';

  final config = new QonversionConfigBuilder(
    'projectKey',
    QLaunchMode.subscriptionManagement
  )
   .enableKidsMode()
   .build();
  Qonversion.initialize(config);
  ```

  ```typescript React Native theme={null}
  import Qonversion, {
    QonversionConfigBuilder,
    LaunchMode,
  } from '@qonversion/react-native-sdk';

  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
   .enableKidsMode()
   .build();
  Qonversion.initialize(config);
  ```

  ```csharp Unity theme={null}
  using QonversionUnity;

  private void Start()
  {
      QonversionConfig config = new QonversionConfigBuilder(
              "projectKey",
              LaunchMode.SubscriptionManagement
          )
           .EnableKidsMode()
           .Build();
      Qonversion.Initialize(config);
  }
  ```

  ```typescript Cordova theme={null}
  const config = new Qonversion.ConfigBuilder(
    'projectKey',
    Qonversion.LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
   .enableKidsMode()
   .build();
  Qonversion.initialize(config);
  ```

  ```typescript Capacitor theme={null}
  import Qonversion, {
    QonversionConfigBuilder,
    LaunchMode,
  } from '@qonversion/capacitor-plugin';

  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
   .enableKidsMode()
   .build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

***

[iOS App Extensions](ios-app-extensions)

[watchOS/visionOS](watchosvisionos)


# Kochava
Source: https://documentation.qonversion.io/docs/kochava

Send iOS and Android in-app subscription events to Kochava with Qonversion.

Qonversion sends subscription data for iOS and Android apps to your Kochava account to help you understand your marketing performance. Measure what drives your revenue by tracking trial-to-paying-user conversion, subscription renewals, refunds, and other useful subscription events.

## 1. Set up the SDKs

1. You need to have Kochava SDK integrated into your app before starting with this integration. If you do not have Kochava integration yet, please use [this documentation](https://www.kochava.com/download-the-sdk/).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Provide to Qonversion Kochava deviceId through user-properties:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.kochavaDeviceID, value: KochavaTracker.shared.deviceIdString)
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyKochavaDeviceID value:[KochavaTracker.shared deviceIdString]];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.KochavaDeviceId, Tracker.getDeviceId());
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.KochavaDeviceId, Tracker.getDeviceId())
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.kochavaDeviceId, 'your kochava device id');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.KOCHAVA_DEVICE_ID, 'your kochava device id');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.KochavaDeviceId, "your kochava device id");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.KOCHAVA_DEVICE_ID, 'your kochava device id');
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.KOCHAVA_DEVICE_ID, 'your kochava device id');
  ```
</CodeGroup>

**→[Read more about User Properties here](user-properties)**

## 2. Configure the Kochava Integration

1. Log in to Kochava. Create and copy your API Key, also copy your Secret Key. Follow [this documentation](https://support.kochava.com/analytics-reports-api/create-and-manage-application-programming-interface-key/) to find how to create and manage API Key.

2. Navigate to the Integrations section in your Qonversion project, select [Kochava](https://dash.qonversion.io/app/integration/kochava), and provide the **API Key**, **Secret Key**, and **Kochava App GUID**, and Save.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Kochava account.
</Check>

## Event Payload

In case you need details about data sent to Kochava, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "action":"event",
     "kochava_app_id":"",
     "kochava_device_id":"",
     "data":{
        "event_name":"subscription_renewed",
        "device_ver":"iPhone 8",
        "usertime":1686178982,
        "origination_ip":"000.000.00.0",
        "device_ua":"",
        "device_ids":{
           "idfa":""
        },
        "event_data":{
           "id":000000000,
           "name":"product_id",
           "price":21.2415,
           "currency":"USD"
        },
        "app_version":"2.0"
     }
  }
  ```
</CodeGroup>

***

[Google Cloud Storage](google-cloud-storage)

[Mailchimp](mailchimp)


# Launch experiments
Source: https://documentation.qonversion.io/docs/launch-experiments

Plan, configure, and launch monetisation experiments with flexible A/B testing solution

This guide helps you walk through four main steps to launch your experiment:

1. Plan your experiment
2. Configure and test variants
3. Adjust traffic level
4. Launch the experiment

## 1. Plan your experiment

<Info>
  ### Leveraging existing Remote Config

  If you already use our Remote Config feature and have paywalls or onboarding flows configured, you can launch the experiment right from existing configurations. [Learn more here.](launch-test-from-remote-config)
</Info>

## Start with your idea

Writing down your idea beforehand helps to avoid several biases (for instance, confirmation bias) during experiment analyses. At the start, we recommend you focus on the following sections:

* **Experiment name**, as the title of your experiment, helps you understand your main idea at a glance.

* **Context key**, as an identification of your application context on the SDK side, helps you target experiments for specific parts of your user journey. Examples of app contexts you may experiment with:

  * *main\_paywall*: to validate ideas for the content different user segments see on your main paywall.
  * *main\_paywall\_products*: to run experiments only for the products section.
  * *onboarding*: to check how changes related to the entire user onboarding journey affect your revenue.
  * *onboarding\_step\_2*: to validate changes for some specific steps of your onboarding flow.
  * *\[your\_key]*: to run experiments for any other part of your user's monetization experience.

* **Hypothesis description**, as a short idea representation, helps you stay focused on what you intended to validate initially.

<img alt="" />

## Choose your Primary Metric

After filling in the main information, you can select the Primary Metric for the experiment. Setting primary metrics in this step helps you get information about statistical significance and recommended sample size during the experiment analysis phase. Qonversion metrics you can choose from:

* User-to-Trial Conversion
* User-to-Paid Conversion
* New Trials
* Trial-to-Paid Conversion
* Trials Cancellation Rate
* New Subscriptions
* Subscriptions Cancellation Rate
* Sales
* Proceeds
* Refunds

<img alt="" />

## 2. Configure and test variants

<Info>
  ### Prerequisites

  To enable Qonversion to run and calculate A/B testing results, you need to have [Qonversion SDK installed](quickstart) in your app.
</Info>

By using Qonversion Experiments, you can test any part of your paywall (and even more). Moreover, Experiments and Remote Config share the same API & architectural concepts, so you do not need to implement complex logic to use both. For how assignments, caching, and identity interact, see [How targeting and assignment works](/docs/remote-config-targeting).

## Use various data types

Qonversion Experiments work with the same in-app values as Remote Config. The core of these attributes is a plain JSON file consisting of key-value data. We support the following data types:

* **String**.

  * Use this option to validate pricing, communication, or visual hypothesis.
  * Examples: *native.subs.full.v4.w\.8.99.trial.7d*, *Unlock Fast and Secure Browsing*, *#3076FF*, etc.

* **Number**.

  * Use this option, for example, to show only a subset of your onboarding screens.
  * Examples: *2*, *5*, *23*, etc.

* **Boolean**.

  * Use this option to turn some features on or off.
  * Examples: *true*, *false*

* **Json**.

  * Use this option to validate advanced changes in your app's behavior.
  * Examples: `{"banner_text": "Choose your plan", "product_top": "native.subs.full.v4.w.8.99.trial.7d", "product_bottom": "subs.month.17.99", "skip_onboarding": true}`.

<img alt="" />

## Get your configuration

<Info>
  ### Configuration source

  Qonversion Remote Configs and Experiments share single methods to get configurations. You can distinguish the source of the result received by looking at the *source* field. [Learn more about fields available](launch-experiments#remoteconfig-fields-description).
</Info>

To receive the configuration **with the Context key set**, call the following Qonversion `remoteConfig` method.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig(contextKey: "my_context_key") { remoteConfig, error in
      // Use remoteConfig here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfig:@"my_context_key" completion:^(QONRemoteConfig * _Nullable remoteConfig, NSError * _Nullable error) {
      // Use remoteConfig here
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig("my_context_key", object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          // Use remoteConfig here
      }

      override fun onError(error: QonversionError) {
          // Handle error here
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfig("my_context_key", new QonversionRemoteConfigCallback() {
      @Override
      public void onSuccess(@NonNull QRemoteConfig remoteConfig) {
          // Use remoteConfig here
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // Handle error here
      }
  });
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: "my_context_key");
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig("my_context_key", (remoteConfig, error) =>
  {
      // Use remoteConfig here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');
  ```

  ```typescript Capacitor theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');
  ```
</CodeGroup>

In case you're using configurations **with empty Context key**, call the same method with no arguments added:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig { remoteConfig, error in
      // Use remoteConfig here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfig:^(QONRemoteConfig * _Nullable remoteConfig, NSError * _Nullable error) {
      // Use remoteConfig here
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig(object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          // Use remoteConfig here
      }

      override fun onError(error: QonversionError) {
          // Handle error here
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfig(new QonversionRemoteConfigCallback() {
      @Override
      public void onSuccess(@NonNull QRemoteConfig remoteConfig) {
          // Use remoteConfig here
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // Handle error here
      }
  });
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig((remoteConfig, error) =>
  {
      // Use remoteConfig here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```

  ```typescript Capacitor theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```
</CodeGroup>

If necessary, you can also request a list of remote configs for all the context keys, including the empty one.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfigList { remoteConfigList, error in
    // Use remoteConfigList here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfigList:^(QONRemoteConfigList * _Nullable remoteConfigList, NSError * _Nullable error) {
    // Use remoteConfigList here
  }]
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfigList(object : QonversionRemoteConfigListCallback {
      override fun onSuccess(remoteConfigList: QRemoteConfigList) {
          // Use remoteConfigList here
      }

      override fun onError(error: QonversionError) {
          // Handle error here
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfigList(new QonversionRemoteConfigListCallback() {
      @Override
      public void onSuccess(@NonNull QRemoteConfigList remoteConfigList) {
        // Use remoteConfigList here
      }

      @Override
      public void onError(@NonNull QonversionError error) {
        // Handle error here
      }
  });
  ```

  ```typescript React Native theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```

  ```dart Flutter theme={null}
  final remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfigList((remoteConfigList, error) =>
  {
      // Use remoteConfigList here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```

  ```typescript Capacitor theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```
</CodeGroup>

If you need remote configs for a specific set of context keys, just use the following method.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfigList(
    contextKeys: ["my_context_key", "another_context_key"],
    includeEmptyContextKey: true // to include remote config without context key
  ) { remoteConfigList, error in
    // Use remoteConfigList here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfigList:@[@"my_context_key", @"another_context_key"]
                         includeEmptyContextKey:YES // to include remote config without context key
   																	 completion:^(QONRemoteConfigList * _Nullable remoteConfigList, NSError * _Nullable error) {
    // Use remoteConfigList here
  }
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfigList(
      listOf("my_context_key", "another_context_key"),
      true, // to include remote config without context key
      object : QonversionRemoteConfigListCallback {
          override fun onSuccess(remoteConfigList: QRemoteConfigList) {
              // Use remoteConfigList here
          }

          override fun onError(error: QonversionError) {
              // Handle error here
          }
  	  }
  )
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfigList(
      Arrays.asList("my_context_key", "another_context_key"),
      true, // to include remote config without context key
      new QonversionRemoteConfigListCallback() {
          @Override
          public void onSuccess(@NonNull QRemoteConfigList remoteConfigList) {
              // Use remoteConfigList here
          }

          @Override
          public void onError(@NonNull QonversionError error) {
              // Handle error here
          }
  		}
  );
  ```

  ```typescript React Native theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ['my_context_key', 'another_context_key'],
    true // to include remote config without context key
  );
  ```

  ```dart Flutter theme={null}
  final remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ["my_context_key", "another_context_key"],
    true // to include remote config without context key
  );
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfigList(
    new string[] {"my_context_key", "another_context_key"},
    true, // to include remote config without context key
    (remoteConfigList, error) =>
  {
      // Use remoteConfigList here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ['my_context_key', 'another_context_key'],
    true // to include remote config without context key
  );
  ```

  ```typescript Capacitor theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ['my_context_key', 'another_context_key'],
    true // to include remote config without context key
  );
  ```
</CodeGroup>

### `RemoteConfigList` fields description

| Field                          | Description                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
| remoteConfigs                  | All the available remote configs. List of `RemoteConfig`.                                        |
| remoteConfigForContextKey      | Available remote config from the list above, filtered by the context key. Single `RemoteConfig`. |
| remoteConfigForEmptyContextKey | Available remote config from the list above, with no context key set. Single `RemoteConfig`.     |

### `RemoteConfig` fields description

| Field      | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| payload    | JSON payload you have configured using the Qonversion dashboard. |
| experiment | Object (`Experiment`) with the experiment's information.         |
| source     | Source (`RemoteConfigurationSource`) of the configuration.       |

### `Experiment` description

| Field         | Description                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------- |
| identifier/id | Experiment's identifier.                                                                      |
| name          | Experiment's name. The same as you set in Qonversion. You can use it for analytical purposes. |
| group         | Experiment's group (`ExperimentGroup`) the user has been assigned to.                         |

### `ExperimentGroup` description

| Field         | Description                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------- |
| identifier/id | Experiment group's identifier.                                                                      |
| name          | Experiment group's name. The same as you set in Qonversion. You can use it for analytical purposes. |
| type          | Type of the experiment's group. Either control or treatment.                                        |

### `RemoteConfigurationSource` description

| Field          | Description                                                                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| identifier/id  | Either experiment's or remote config's ID.                                                                                                                                                                                                                                            |
| name           | Either experiment's or remote config's name.                                                                                                                                                                                                                                          |
| assignmentType | How the current payload was assigned: `automatic` (sticky, re-evaluated on targeting changes) or `manual` (overrides targeting, never re-evaluated until detach/archive/delete — including pins created by [Freeze assignments](/docs/remote-config-targeting#freezing-assignments)). |
| type           | One of the following: experiment control group, experiment treatment group, remote configuration.                                                                                                                                                                                     |
| contextKey     | Context key assigned to either experiment or remote config.                                                                                                                                                                                                                           |

## Test experimental changes before launch

<Info>
  Please, note, the guide below allows you to test only configurations created through the [Experiments dashboard section](https://dash.qonversion.io/ab-testing). To test configurations from the [Remote Config section](https://dash.qonversion.io/remote-configs), please, follow the [test changes before launch](remote-config#test-changes-before-launch) guide.
</Info>

We highly recommend testing if your app works properly with the changes you want to roll out to your users. You can do so by following the following steps:

1. Copy the ID for your experiment and the variant you want to test.

<img alt="" />

2. Pass the values to Qonversion SDK by using the `attachUserToExperiment` method

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().attachUser(toExperiment: "your_experiment_id", groupId: "your_group_id") { success, error in
       // handle result
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] attachUserToExperiment:@"your_experiment_id" groupId:@"your_group_id" completion:^(BOOL success, NSError * _Nullable error) {
      // handle result
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.attachUserToExperiment("your_experiment_id", "your_group_id", object : QonversionExperimentAttachCallback {
      override fun onSuccess() {
          // handle success
      }

      override fun onError(error: QonversionError) {
          // handle error
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().attachUserToExperiment("your_experiment_id", "your_group_id", new QonversionExperimentAttachCallback() {
      @Override
      public void onSuccess() {
          // handle success
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error
      }
  });
  ```

  ```typescript React Native theme={null}
  await Qonversion.getSharedInstance().attachUserToExperiment("your_experiment_id", "your_group_id");
  ```

  ```dart Flutter theme={null}
  await Qonversion.getSharedInstance().attachUserToExperiment("your_experiment_id", "your_group_id");
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().AttachUserToExperiment("your_experiment_id", "your_group_id", (success, error) =>
  {
      // handle result
  });
  ```

  ```typescript Cordova theme={null}
  await Qonversion.getSharedInstance().attachUserToExperiment("your_experiment_id", "your_group_id");
  ```

  ```typescript Capacitor theme={null}
  await Qonversion.getSharedInstance().attachUserToExperiment("your_experiment_id", "your_group_id");
  ```
</CodeGroup>

* In case your user has already been attached to another experiment, use the `detachUserFromExperiment` method.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().detachUser(fromExperiment: "attached_experiment_id") { success, error in
      // handle result
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] detachUserFromExperiment:@"attached_experiment_id" completion:^(BOOL success, NSError * _Nullable error) {
      // handle result
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.detachUserFromExperiment("attached_experiment_id", object : QonversionExperimentAttachCallback {
      override fun onSuccess() {
          // handle success
      }

      override fun onError(error: QonversionError) {
          // handle error
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().detachUserFromExperiment("attached_experiment_id", new QonversionExperimentAttachCallback() {
      @Override
      public void onSuccess() {
          // handle success
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error
      }
  });
  ```

  ```typescript React Native theme={null}
  await Qonversion.getSharedInstance().detachUserFromExperiment("attached_experiment_id");
  ```

  ```dart Flutter theme={null}
  await Qonversion.getSharedInstance().detachUserFromExperiment("attached_experiment_id");
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().DetachUserFromExperiment("attached_experiment_id", (success, error) =>
  {
      // handle result
  });
  ```

  ```typescript Cordova theme={null}
  await Qonversion.getSharedInstance().detachUserFromExperiment("attached_experiment_id");
  ```

  ```typescript Capacitor theme={null}
  await Qonversion.getSharedInstance().detachUserFromExperiment("attached_experiment_id");
  ```
</CodeGroup>

3. Call the Qonversion `remoteConfig` method. Now Qonversion SDK returns data associated with previously set experiment and variant.
4. Validate your app logic without starting the experiment.

<Warning>
  ### Pay attention before release

  Do not forget to remove the usage of the `attachUserToExperiment` method before your app release. Otherwise, all your users may be exposed to only one experiment group.
</Warning>

## Segment your users

You have the following segmentation opportunities at your disposal:

* **App install date**
  * Use this option to assign the configuration only to new app installs.
* **App version**
  * Use this option to assign the configuration only for users with the app version with the new features implemented. This is your app's **version name**, not its build number — `versionName` on Android (never `versionCode`) and `CFBundleShortVersionString` on iOS (never `CFBundleVersion`). See [Matching on app version](remote-config#matching-on-app-version) for the comparison rules.
* **Attached active experiment**
  * Use this option to include or exclude users already exposed to other active experiments. [Learn more about experiment assigning rules](splitting-rules).
* **Attached experiment context key**
  * Use this option to include or exclude users already exposed to other active experiments *with specific context keys*. [Learn more about experiment assigning rules](splitting-rules).
* **Country**
  * Use this option to run new behavior only in selected countries.
* **Store**
  * Use this option to target only a specific store (Apple App Store or Google Play).
* **User's active subscription**
  * Use this option to target only users with/without any active subscriptions or having a specific one.
* **Purchased product**
  * Use this option to target users based on their purchase history. You can select specific products or use `(any)` to match users who made at least one purchase, or `(none)` for users with no purchase history. Unlike "Active subscription", this filter checks all purchases regardless of their current status (active, expired, or cancelled).
* **Last purchase date**
  * Use this option to target users based on when they made their most recent purchase. For example, you can target users whose last purchase was more than 60 days ago to identify churned users.
* **User properties**
  * Use this option to target users with specific custom user properties set via the SDK. Useful for behavior-based or attribute-based experiments.

For how segmentation combines with the rollout percentage and sticky assignments, see [How targeting and assignment works](/docs/remote-config-targeting).

## 3. Adjust traffic level

We do not recommend starting your experiments with 100% of all eligible users. It might be enough to start with 10% to ensure everything works fine and increase your traffic level later.

<Note>
  Raising the traffic level later admits only users the experiment has **never evaluated** — users once rejected by the traffic gate stay excluded. Plan the initial allocation with this in mind; see [Changing experiment traffic mid-flight](/docs/remote-config-targeting#changing-experiment-traffic-mid-flight).
</Note>

<img alt="" />

## 4. Launch the setup

Once you have configured your experiment, segmentation, and traffic level, it's time to start your experiment and proceed to the section with real-time analytics.

<img alt="" />

***

What’s Next

* [Analyse experiments](analyse-experiment)
* [Splitting rules](splitting-rules)


# Launch A/B test from Remote Config
Source: https://documentation.qonversion.io/docs/launch-test-from-remote-config

Iterate with monetization A/B tests without app releases

## 1. Create experiment from configuration

If you do not have [Remote Config](https://dash.qonversion.io/remote-configs) created yet, please, make it first.

After you have your configuration launched, you can start experiments based on it:

1. Find the configuration's context menu.
2. Click the "Create Experiment" button.
3. Adjust relevant keys to set up your new app behavior.
4. [Validate change](launch-experiments#test-changes-before-launch) before app release.
5. [Set traffic level](launch-experiments#3-adjust-traffic-level) and [launch the experiment](launch-experiments#4-launch-the-setup).

<Frame>
  <img />
</Frame>

## 2. Create configuration from experiment

Once your hypothesis is validated, you might want to create a new Remote Configuration containing new payload or segmentation settings without additional app releases.

With this in mind, we have built a seamless approach that enables you to create new configurations from the experiment interface. **End** your experiment and select the **Create Remote Config** option.

Ending the experiment releases all its users, so the new configuration starts with a clean slate: everyone is evaluated fresh against its targeting rules — experiment group membership does not carry over.

## 3. Archive old Remote Config

After creating a new configuration during Step #2, you have two similar entities running:

* The one you started from during [Step #1](launch-test-from-remote-config#1-create-experiment-from-configuration).
* The one you have launched during [Step #2](launch-test-from-remote-config#2-create-configuration-from-experiment).

We highly recommend archiving the old configuration (from step #1) to avoid unexpected behavior. To accomplish this:

1. Follow the [Remote Config](https://dash.qonversion.io/remote-configs) page in Qonversion dashboard.
2. Find and click on the previously created configuration.
3. Open the **⋯** (More actions) menu in the top-right corner and select **Archive** to stop it from running.

<Frame>
  <img />
</Frame>

## 4. Repeat

Congratulations! Following the abovementioned steps, you have completed your first *configuration -> experiment -> rollout* cycle. Now, you can leverage remotely configured onboarding flows, paywalls, or pricing to grow your in-app revenue. Moreover, our concept allows you to iterate without app releases.

***

[Create Remote Config](remote-config)

[Paywall experiments](paywall-experiments)


# License testing
Source: https://documentation.qonversion.io/docs/license-testing

Set up Gmail license test accounts in Google Play Console to test Android in-app purchases and subscriptions without real charges.

Application licensing allows you to set up a list of Gmail accounts to test your in-app purchases. You don't have to add a publishing account here because it is considered a licensed tester by default.

**1. Open License Testing panel** Navigate to [Google Play Developer Console](https://play.google.com/apps/publish/). Click on the Settings and select the **License Testing** panel. This page lets you set up the main components for test accounts and manage test responses.

**2. License testers** Add the tester account that you will use for testing in-app purchases with an Android device. See more on Android devices for testing [here](android-test-devices).

**3. License response** License response allows you to set a [static licensing response](https://developer.android.com/google/play/licensing/setting-up#test-response) in your publisher account. RESPOND\_NORMALLY affects google server responses when it receives a license check for your application. If the app has a license, the server will respond "LICENSED". Otherwise "NOT\_LICENSED".

<img alt="1249" />

***

What’s Next

* [Android In-App Purchases Setup](android-in-app-products)
* [Android test devices](android-test-devices)


# Overview
Source: https://documentation.qonversion.io/docs/llmtxt

We've added a special file—llms.txt—to help AI tools like ChatGPT, Google Gemini, Claude, and Perplexity better understand and process the content of our website.

This file provides guidance to large language models (LLMs), improving how our site is interpreted in AI-powered environments. It’s similar in concept to robots.txt, but specifically designed for AI comprehension.

You can view it here:

[https://documentation.qonversion.io/llms.txt](https://documentation.qonversion.io/llms.txt)

No action is needed on your part—this helps ensure our platform content is more accessible and accurately represented across modern AI systems.


# macOS / Catalyst
Source: https://documentation.qonversion.io/docs/macos-catalyst

Qonversion SDK to handle in-app purchases for macOS / Catalyst

Qonversion is the data platform to power in-app subscription revenue growth. Qonversion allows fast in-app subscriptions implementation. It provides the back-end infrastructure to validate user receipts and manage cross-platform user access to paid content on your app, so you do not need to build your server. Qonversion also provides comprehensive subscription analytics and out-of-the-box integrations with the leading marketing, attribution, and product analytics platforms.

Qonversion iOS SDK is compatible with macOS and can be installed via CocoaPods or Swift Package Manager.

## Install via CocoaPods

Add dependency to `Podfile`.

<CodeGroup>
  ```bash Podfile theme={null}
  pod 'Qonversion'
  ```
</CodeGroup>

Run pod install in the project directory to download dependency.

<CodeGroup>
  ```bash Terminal theme={null}
  pod install
  ```
</CodeGroup>

## Install via Swift Package Manager

Open Xcode, go to **File → Swift Packages → Add Package Dependency** and enter the package URL `https://github.com/qonversion/qonversion-ios-sdk` to import the package through SPM.

<NextStepsChooseMode />


# Mailchimp
Source: https://documentation.qonversion.io/docs/mailchimp

Send iOS and Android subscription events to Mailchimp to trigger personalized emails

Qonversion sends mobile subscription events to Mailchimp to automate emails with special offers to users who cancel a trial or a subscription. A personalized email with a special offer to a user who just canceled his trial can significantly uplift your app's revenue. You need to provide a user email address using Qonversion's user properties to be able to use Mailchimp integration.

## 1. Configure the SDK

1. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

2. Provide user email using [User Properties](user-properties):

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.email, value: "me@qonversion.io")
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyEmail value:@"me@qonversion.io"];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.Email, "me@qonversion.io");
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.Email, "me@qonversion.io")
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.email, 'me@qonversion.io');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.EMAIL, 'me@qonversion.io');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.Email, "me@qonversion.io");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.EMAIL, 'me@qonversion.io');
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.EMAIL, 'me@qonversion.io');
  ```
</CodeGroup>

**→[Read more about User Properties here](user-properties)**

<Warning>
  ### Attention

  You need to provide user email using user properties to Qonversion. Qonversion will be able to send events to Mailchimp only for the users with the correct user email provided. Please check how to add user email to Qonversion [here](user-properties#defined-user-properties)

  Qonversion is sending the code of the registered event \{"name": "trial\_started"} to [https://mailchimp.com/developer/marketing/api/list-member-events/add-event/](https://mailchimp.com/developer/marketing/api/list-member-events/add-event/) endpoint. User ID of the MailChimp user (subscriber\_hash) is generated based on the user's email.
</Warning>

<Note>
  ### Auto-subscribe on first event

  If the user's email is not yet a subscriber in the configured audience, the first event call returns 404. Qonversion then creates the subscriber via Mailchimp's `POST /lists/{list_id}/members` endpoint with `status: "subscribed"` and retries the event call. As a result, you may see auto-created subscribers in your Mailchimp audience for users who provided their email through Qonversion but never explicitly opted in.
</Note>

## 2. Configure the Mailchimp Integration

1. Get your Mailchimp [API KEY](https://mailchimp.com/help/about-api-keys/) and [Audience ID](https://mailchimp.com/help/find-audience-id/)

2. Open the [**Integrations**](https://dash.qonversion.io/integrations) section in your Qonversion project, click **+ Add new**, choose **Mailchimp**, then provide the **API Key** and **Audience ID** (also known as List ID) and save.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Mailchimp account.
</Check>

***

[Kochava](kochava)

[Mixpanel](mixpanel)


# How to make purchases with the Qonversion SDK
Source: https://documentation.qonversion.io/docs/making-purchases

Make in-app purchases with the Qonversion SDK: start a purchase, handle the success/cancel/pending/error result, restore purchases, and use Android offers, subscription updates, and iOS multi-quantity options.

Before you handle purchases with the Qonversion SDK, [configure Products and Entitlements](subscription-management-mode) in the Qonversion dashboard. `product` in every example below is a Qonversion Product you created in the [dashboard](https://dash.qonversion.io/entitlements/products); see [Displaying Products](displaying-products) to fetch and display them.

<span />

## Make a purchase

Start a purchase with the `purchase()` method (Swift), `purchaseWithResult:` (Objective-C), or `purchase()` on Android and the cross-platform SDKs. The method returns a purchase result object; when the purchase succeeds, look up the granted entitlement on `result.entitlements`.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().purchase(product) { (result) in
    if result.isSuccessful {
      if let premium: Qonversion.Entitlement = result.entitlements["premium"], premium.isActive {
        // Grant user access to premium features
      }
    } else if result.isCanceledByUser {
      // Handle canceled purchase
    } else if result.isPending {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
    if (result.isSuccessful) {
      QONEntitlement *premiumEntitlement = result.entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        // Grant user access to premium features
      }
    } else if (result.isCanceledByUser) {
      // Handle canceled purchase
    } else if (result.isPending) {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().purchase(this, product, new QonversionPurchaseCallback() {
      @Override
      public void onResult(@NonNull QPurchaseResult result) {
          if (result.isSuccessful()) {
              QEntitlement premium = result.getEntitlements().get("premium");
              if (premium != null && premium.isActive()) {
                  // Grant user access to premium features
              }
          } else if (result.isCanceledByUser()) {
              // Handle canceled purchase
          } else if (result.isPending()) {
              // Handle pending purchase
          } else {
              // Handle errors
          }
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.purchase(requireActivity(), product, object : QonversionPurchaseCallback {
      override fun onResult(result: QPurchaseResult) {
          when {
              result.isSuccessful -> {
                  val premium = result.entitlements["premium"]
                  if (premium != null && premium.isActive) {
                      // Grant user access to premium features
                  }
              }
              result.isCanceledByUser -> {
                  // Handle canceled purchase
              }
              result.isPending -> {
                  // Handle pending purchase
              }
              else -> {
                  // Handle errors
              }
          }
      }
  })
  ```

  ```dart Flutter theme={null}
  final result = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    final premium = result.entitlements?['premium'];
    if (premium != null && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript React Native theme={null}
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Purchase(product, (result) =>
  {
      if (result.IsSuccess)
      {
          if (result.Entitlements != null &&
              result.Entitlements.TryGetValue("premium", out var premium) &&
              premium.IsActive)
          {
              // Grant user access to premium features
          }
      }
      else if (result.IsCanceled)
      {
          // Handle canceled purchase
      }
      else if (result.IsPending)
      {
          // Handle pending purchase
      }
      else
      {
          // Handle errors
      }
  });
  ```

  ```typescript Cordova theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript Capacitor theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```
</CodeGroup>

## Handle a purchase result

The purchase method returns a single result object on every platform — it does not throw for a user cancellation or a pending purchase. Inspect the status flags and branch on all four cases:

* **Success** — `isSuccess` (`isSuccessful` on iOS/Android; `IsSuccess` on Unity). Grant access; read the granted entitlement from `result.entitlements`.
* **Canceled by the user** — `isCanceled` (`isCanceledByUser` on iOS/Android; `IsCanceled` on Unity). Do not grant access.
* **Pending** — `isPending` (`IsPending` on Unity). The transaction is queued and awaiting an external action (for example, Ask to Buy or a deferred payment); do not grant access yet.
* **Error** — none of the above. Handle the error (see [Purchase errors](#purchase-errors)).

Entitlement IDs are the keys to the `entitlements` map. The values are [Qonversion.Entitlement](check-permissions#the-entitlement-object) objects.

## Purchase errors

When a purchase fails, the SDK returns an error rather than an entitlement. The full list of purchase error codes, their iOS `QONErrorCode` names, and Android names is on the [Handling Errors](handling-errors) page. The most common purchase errors and where to fix them:

| Error                 | iOS `QONErrorCode`                 | Android name          | What it means                                                                                                                                                                                 |
| --------------------- | ---------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Purchase canceled     | `QONErrorCodePurchaseCanceled` (1) | `PurchaseCanceled`    | The user canceled the purchase request. Surfaced as the `isCanceled` flag, not an error branch, on most platforms.                                                                            |
| Product not found     | `QONErrorCodeProductNotFound` (2)  | `ProductNotFound`     | The product could not be found. See [Product not found error](troubleshooting#product-not-found-error).                                                                                       |
| Product already owned | —                                  | `ProductAlreadyOwned` | The item is already owned, so it cannot be purchased again.                                                                                                                                   |
| Purchase pending      | `QONErrorCodePurchasePending` (18) | —                     | The payment is queued and its final status is pending external action. Surfaced as the `isPending` flag.                                                                                      |
| Purchase invalid      | `QONErrorCodePurchaseInvalid` (31) | `PurchaseInvalid`     | The purchase failed — for example, a purchase with such `purchaseToken` cannot be found, or the store key belongs to another project. See the [Google Play billing setup guide](google-play). |
| Store error           | `QONErrorCodeAppleStoreError` (30) | `PlayStoreError`      | The App Store or Play Store is unavailable, times out, disconnects, or returns an unexpected response.                                                                                        |
| Fraud purchase        | `QONErrorCodeFraudPurchase` (28)   | `FraudPurchase`       | A fraudulent purchase was detected.                                                                                                                                                           |

## Restore purchases

When a user switches to a new device, call `restore()` so they keep access to premium features. Restoring returns the user's current entitlements; it does not create a new purchase or charge the user.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().restore { [weak self] (entitlements, error) in
    if let error = error {
      // Handle error
    }

    if let entitlement: Qonversion.Entitlement = entitlements["plus"], entitlement.isActive {
      // Restored and entitlement is active
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] restore:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull result, NSError * _Nullable error) {
    if (error) {
      // Handle error
    }
    QONEntitlement *entitlement = result[@"active"];
    if (entitlement && entitlement.isActive) {
      // Restored and entitlement is active
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().restore(new QonversionEntitlementsCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
          QEntitlement premiumEntitlement = entitlements.get("premium");

          if (premiumEntitlement != null && premiumEntitlement.isActive()) {
              // handle active entitlement here
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.restore(object : QonversionEntitlementsCallback {
      override fun onSuccess(entitlements: Map<String, QEntitlement>) {
          val premiumEntitlement = entitlements["premium"]
          if (premiumEntitlement != null && premiumEntitlement.isActive) {
              // handle active entitlement here
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().restore();
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
    const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().restore();
   } catch (e) {
    console.log(e);
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Restore((entitlements, error) =>
  {
        if (error == null)
        {
           // Handle entitlements here
        }
        else
        {
          // Handle the error
          Debug.Log("Error" + error.ToString());
        }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await Qonversion.getSharedInstance().restore();
  } catch (e) {
      console.log(e);
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().restore();
   } catch (e) {
    console.log(e);
  }
  ```
</CodeGroup>

<span />

## Check user entitlements

To check a user's entitlements separately from a purchase — for example, on app launch — use the `checkEntitlements()` method. See [Check user entitlements](check-permissions) for details.

## Consumable in-app purchases

Consumable in-app purchases are not tied to an entitlement, so when you make a consumable purchase you only look at the outcome (success or error), not at entitlements. On success, grant the bonus; on error, do not. The flow is:

1. The customer initiates the consumable in-app purchase.
2. You call the Qonversion purchase method.
3. You receive the purchase response:
   1. Successful response — grant the user the bonus.
   2. Error — do not grant any bonus.

On iOS and Android you can also read the completed store transaction from the result (`result.transaction` on iOS, `result.purchase` on Android, `result.storeTransaction` on the cross-platform SDKs):

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().purchase(product) { (result) in
    if result.isSuccessful {
      // Grant coins here
      // Also check the store transaction if necessary
      if let transaction = result.transaction {

      }
    } else if result.isCanceledByUser {
      // Handle canceled purchase
    } else if result.isPending {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
    if (result.isSuccessful) {
      // Grant coins here
      // Also check the store transaction if necessary
      if (result.transaction != nil) {

      }
    } else if (result.isCanceledByUser) {
      // Handle canceled purchase
    } else if (result.isPending) {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().purchase(this, product, new QonversionPurchaseCallback() {
      @Override
      public void onResult(@NonNull QPurchaseResult result) {
          if (result.isSuccessful()) {
              // Grant coins here
              // Also check the store purchase if necessary
              if (result.purchase != null) {

              }
          } else if (result.isCanceledByUser()) {
              // Handle canceled purchase
          } else if (result.isPending()) {
              // Handle pending purchase
          } else {
              // Handle errors
          }
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.purchase(requireActivity(), product, object : QonversionPurchaseCallback {
      override fun onResult(result: QPurchaseResult) {
          when {
              result.isSuccessful -> {
                  // Grant coins here
                  // Also check the store purchase if necessary
                  result.purchase?.let {

                  }
              }
              result.isCanceledByUser -> {
                  // Handle canceled purchase
              }
              result.isPending -> {
                  // Handle pending purchase
              }
              else -> {
                  // Handle errors
              }
          }
      }
  })
  ```

  ```dart Flutter theme={null}
  final result = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    // Grant coins here
    // Also check the store purchase if necessary
    if (result.storeTransaction != null) {

    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript React Native theme={null}
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    // Grant coins here
    // Also check the store purchase if necessary
    if (result.storeTransaction) {

    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Purchase(product, (result) =>
  {
      if (result.IsSuccess)
      {
          // Grant coins here
          // Also check the store purchase if necessary
          if (result.StoreTransaction != null)
          {

          }
      }
      else if (result.IsCanceled)
      {
          // Handle canceled purchase
      }
      else if (result.IsPending)
      {
          // Handle pending purchase
      }
      else
      {
          // Handle errors
      }
  });
  ```

  ```typescript Cordova theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    // Grant coins here
    // Also check the store purchase if necessary
    if (result.storeTransaction) {

    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript Capacitor theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    // Grant coins here
    // Also check the store purchase if necessary
    if (result.storeTransaction) {

    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```
</CodeGroup>

## Android: choose a specific offer

*Android only.* The Google Play Billing Library lets you sell a subscription with different offers. Read the available offers from `QProduct.storeDetails`, then pass the chosen offer through `QPurchaseOptions`. This is not available on iOS — App Store offers are selected by StoreKit, not by the SDK.

<CodeGroup>
  ```java Java theme={null}
  // Specify the concrete offer:
  final QProductOfferDetails productOfferDetails = ...; // Choose an offer from `storeDetails`
  final QPurchaseOptions purchaseOptions = new QPurchaseOptions.Builder()
          .setOffer(productOfferDetails)
          .build();

  // or specify only the offer ID:
  final QPurchaseOptions purchaseOptions = new QPurchaseOptions.Builder()
          .setOfferId("offer_id")
          .build();

  // and then provide created `QPurchaseOptions` to the `purchase` method:
  Qonversion.getSharedInstance().purchase(this, product, purchaseOptions, new QonversionPurchaseCallback() {
      ...
  });
  ```

  ```kotlin Kotlin theme={null}
  // Specify the concrete offer:
  val productOfferDetails = ... // Choose an offer from `storeDetails`
  val purchaseOptions = QPurchaseOptions.Builder()
      .setOffer(productOfferDetails)
      .build()

  // or specify only the offer ID:
  val purchaseOptions = QPurchaseOptions.Builder()
      .setOfferId("offer_id")
      .build()

  // and then provide created `QPurchaseOptions` to the `purchase` method:
  Qonversion.shared.purchase(this, product, purchaseOptions, callback = object: QonversionPurchaseCallback {
      ...
  })
  ```

  ```dart Flutter theme={null}
  // Specify the concrete offer:
  final productOfferDetails = ... // Choose an offer from `storeDetails`
  final purchaseOptions = QPurchaseOptionsBuilder()
      .setOffer(productOfferDetails)
      .build()

  // or specify only the offer ID:
  final purchaseOptions = QPurchaseOptionsBuilder()
      .setOfferId('offer_id')
      .build()

  // and then provide created `QPurchaseOptions` to the `purchaseWithResult` method:
  final result = await Qonversion.getSharedInstance().purchaseWithResult(
    product,
    purchaseOptions: purchaseOptions
  );
  ```

  ```typescript React Native theme={null}
  // Specify the concrete offer:
  const productOfferDetails = ...; // Choose an offer from `storeDetails`
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOffer(productOfferDetails)
    .build();

  // or specify only the offer ID:
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOfferId('offer_id')
    .build();

  // and then provide created `PurchaseOptions` to the `purchaseWithResult` method:
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product, purchaseOptions);
  ```

  ```csharp Unity theme={null}
  // Specify the concrete offer:
  ProductOfferDetails productOfferDetails = ...; // Choose an offer from StoreDetails
  var purchaseOptions = new PurchaseOptionsBuilder()
      .SetOffer(productOfferDetails)
      .Build();

  // or specify only the offer ID:
  var purchaseOptions = new PurchaseOptionsBuilder()
      .SetOfferId("offer_id")
      .Build();

  // and then provide created PurchaseOptions to the Purchase method:
  Qonversion.GetSharedInstance().Purchase(product, purchaseOptions, (result) =>
  {
      ...
  });
  ```

  ```typescript Cordova theme={null}
  // Specify the concrete offer:
  const productOfferDetails = ...; // Choose an offer from `storeDetails`
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setOffer(productOfferDetails)
    .build();

  // or specify only the offer ID:
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setOfferId('offer_id')
    .build();

  // and then provide created `PurchaseOptions` to the `purchase` method:
  const result = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);
  ```

  ```typescript Capacitor theme={null}
  // Specify the concrete offer:
  const productOfferDetails = ...; // Choose an offer from `storeDetails`
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOffer(productOfferDetails)
    .build();

  // or specify only the offer ID:
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOfferId('offer_id')
    .build();

  // and then provide created `PurchaseOptions` to the `purchase` method:
  const result = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);
  ```
</CodeGroup>

If you provide an offer ID, the SDK tries to find and purchase the offer with that ID for the requested Qonversion product; if no offer with that ID exists, an error is returned. If you do not provide an offer ID for a subscription purchase of a Qonversion product with a specified base plan ID, the SDK chooses the most profitable offer for the client from all available offers — it compares all trial or intro phases and the base plan and picks the cheapest price. For old Qonversion products (no base plan ID specified) and for in-app products, the offer ID is ignored.

You can also remove any intro/trial offer from the purchase to keep only the base plan by calling `removeOffer` on the purchase options builder:

<CodeGroup>
  ```java Java theme={null}
  final QPurchaseOptions purchaseOptions = new QPurchaseOptions.Builder()
          .removeOffer()
          .build();
  ```

  ```kotlin Kotlin theme={null}
  val purchaseOptions = QPurchaseOptions.Builder()
      .removeOffer()
      .build()
  ```

  ```dart Flutter theme={null}
  final purchaseOptions = QPurchaseOptionsBuilder()
      .removeOffer()
      .build()
  ```

  ```typescript React Native theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .removeOffer()
    .build();
  ```

  ```csharp Unity theme={null}
  var purchaseOptions = new PurchaseOptionsBuilder()
      .RemoveOffer()
      .Build();
  ```

  ```typescript Cordova theme={null}
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .removeOffer()
    .build();
  ```

  ```typescript Capacitor theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .removeOffer()
    .build();
  ```
</CodeGroup>

<span />

## Android: update a subscription

*Android only.* Upgrading, downgrading, or changing a subscription on the Google Play Store requires setting the old product and, optionally, a replacement mode through the `QPurchaseOptions` builder. See the [Google Play upgrade/downgrade documentation](https://developer.android.com/google/play/billing/subscriptions#upgrade-downgrade) for details. Subscription updates through this API are not supported on iOS.

<CodeGroup>
  ```java Java theme={null}
  final QPurchaseOptions purchaseOptions = new QPurchaseOptions.Builder()
          .setOldProduct(oldProduct)
          .build();
  Qonversion.getSharedInstance().purchase(this, product, purchaseOptions, new QonversionPurchaseCallback() {
      ...
  });
  ```

  ```kotlin Kotlin theme={null}
  val purchaseOptions = QPurchaseOptions.Builder()
      .setOldProduct(oldProduct)
      .build()
  Qonversion.shared.purchase(this, product, purchaseOptions, callback = object: QonversionPurchaseCallback {
      ...
  })
  ```

  ```dart Flutter theme={null}
  final purchaseOptions = QPurchaseOptionsBuilder()
      .setOldProduct(oldProduct)
      .build();
  final result = await Qonversion.getSharedInstance().purchaseWithResult(
    product,
    purchaseOptions: purchaseOptions
  );
  ```

  ```typescript React Native theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)
    .build();
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product, purchaseOptions);
  ```

  ```csharp Unity theme={null}
  var purchaseOptions = new PurchaseOptionsBuilder()
      .SetOldProduct(oldProduct)
      .SetUpdatePolicy(PurchaseUpdatePolicy.WithTimeProration)
      .Build();
  Qonversion.GetSharedInstance().Purchase(product, purchaseOptions, (result) =>
  {
      ...
  });
  ```

  ```typescript Cordova theme={null}
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)
    .build();
  const result = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);
  ```

  ```typescript Capacitor theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)
    .build();
  const result = await Qonversion.getSharedInstance().purchase(product, purchaseOptions);
  ```
</CodeGroup>

Qonversion supports any replacement mode for the old purchase. Provide the update policy while building the purchase options:

<CodeGroup>
  ```java Java theme={null}
  final QPurchaseOptions purchaseOptions = new QPurchaseOptions.Builder()
          .setOldProduct(oldProduct)
          .setUpdatePolicy(QPurchaseUpdatePolicy.WithTimeProration)
          .build();
  ```

  ```kotlin Kotlin theme={null}
  val purchaseOptions = QPurchaseOptions.Builder()
      .setOldProduct(oldProduct)
      .setUpdatePolicy(QPurchaseUpdatePolicy.WithTimeProration)
      .build()
  ```

  ```dart Flutter theme={null}
  final purchaseOptions = QPurchaseOptionsBuilder()
      .setOldProduct(oldProduct)
      .setUpdatePolicy(QPurchaseUpdatePolicy.withTimeProration)
      .build();
  ```

  ```typescript React Native theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)
    .setUpdatePolicy(PurchaseUpdatePolicy.WITH_TIME_PRORATION)
    .build();
  ```

  ```csharp Unity theme={null}
  var purchaseOptions = new PurchaseOptionsBuilder()
      .SetOldProduct(oldProduct)
      .SetUpdatePolicy(PurchaseUpdatePolicy.WithTimeProration)
      .Build();
  ```

  ```typescript Cordova theme={null}
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)
    .setUpdatePolicy(PurchaseUpdatePolicy.WITH_TIME_PRORATION)
    .build();
  ```

  ```typescript Capacitor theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setOldProduct(oldProduct)
    .setUpdatePolicy(PurchaseUpdatePolicy.WITH_TIME_PRORATION)
    .build();
  ```
</CodeGroup>

The update policy can be one of the following values. The default is `WithTimeProration`.

| Name                  | Description                                                                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChargeFullPrice`     | The new plan takes effect immediately, and the user is charged full price of new plan and is given a full billing cycle of subscription, plus remaining prorated time from the old plan. |
| `ChargeProratedPrice` | The new plan takes effect immediately, and the billing cycle remains the same.                                                                                                           |
| `WithTimeProration`   | The new plan takes effect immediately, and the remaining time will be prorated and credited to the user.                                                                                 |
| `Deferred`            | The new purchase takes effect immediately, the new plan will take effect when the old item expires.                                                                                      |
| `WithoutProration`    | The new plan takes effect immediately, and the new price will be charged on next recurrence time.                                                                                        |

## iOS: multi-quantity purchases

*iOS only.* For in-app products you can choose how many items to buy. On Android the quantity is adjusted directly in the purchase pop-up, so no SDK option is needed; on iOS you must set the quantity beforehand while building the purchase options:

<CodeGroup>
  ```swift Swift theme={null}
  let purchaseOptions = Qonversion.PurchaseOptions(quantity: quantity)
  Qonversion.shared().purchase(product, options: purchaseOptions) { (result) in
    ...
  }
  ```

  ```objectivec Objective-C theme={null}
  QONPurchaseOptions *purchaseOptions = [[QONPurchaseOptions alloc] initWithQuantity:3];
  [[Qonversion sharedInstance] purchaseWithResult:product
                                          options:purchaseOptions
                                       completion:^(QONPurchaseResult * _Nonnull result) {
    ...
  }];
  ```

  ```dart Flutter theme={null}
  final purchaseOptions = QPurchaseOptionsBuilder()
      .setQuantity(3)
      .build();
  final result = await Qonversion.getSharedInstance().purchaseWithResult(
    product,
    purchaseOptions: purchaseOptions
  );
  ```

  ```typescript React Native theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setQuantity(3)
    .build();
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product, purchaseOptions);
  ```

  ```csharp Unity theme={null}
  var purchaseOptions = new PurchaseOptionsBuilder()
      .SetQuantity(3)
      .Build();
  Qonversion.GetSharedInstance().Purchase(product, purchaseOptions, (result) =>
  {
      ...
  });
  ```

  ```typescript Cordova theme={null}
  const purchaseOptions = new Qonversion.PurchaseOptionsBuilder()
    .setQuantity(3)
    .build();
  const result = await Qonversion.getSharedInstance().purchase(
    product,
    purchaseOptions
  );
  ```

  ```typescript Capacitor theme={null}
  const purchaseOptions = new PurchaseOptionsBuilder()
    .setQuantity(3)
    .build();
  const result = await Qonversion.getSharedInstance().purchase(
    product,
    purchaseOptions
  );
  ```
</CodeGroup>


# Apple Ads via MCP
Source: https://documentation.qonversion.io/docs/mcp-apple-ads

Read Apple Search Ads performance and manage campaigns from an AI assistant, with the guardrails that keep it honest

<Note>
  Apple Ads is a **closed beta**. Accounts without it receive `404` from every tool on this page — the same answer as a nonexistent endpoint, by design. Ask support to enable it before wiring an assistant to it.
</Note>

The [MCP server](/docs/mcp-server) exposes the Apple Ads section of the dashboard as four tools: three that read and one family that changes live campaigns. This page covers what each one answers, and — more importantly — the handful of ways their output is easy to misread.

## The tools

| Tool                                                                      | Scope             | What it answers                                                                       |
| ------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------- |
| `get_apple_ads_report`                                                    | `analytics:read`  | Qonversion cohort outcomes joined with Apple spend, per campaign / ad group / keyword |
| `get_apple_ads_series`                                                    | `analytics:read`  | One metric, day by day — the chart behind that report                                 |
| `get_apple_ads_connection_status`                                         | `analytics:read`  | Whether the Apple authorization works, and what it currently allows                   |
| `set_apple_ads_status`, `set_apple_ads_bid`, `set_apple_ads_daily_budget` | `apple_ads:write` | Pause/enable an entity, move a bid, move a daily budget                               |

## Reading the report

`get_apple_ads_report` returns one row per entity at the requested `level`, each carrying a `qonversion` block (cohort outcomes), an `apple` block (spend and delivery), and derived ratios.

<Warning>
  **`avg_cpa` is not CAC.** `apple.avg_cpa` is Apple's cost per tap-through *install*. The cost of acquiring a **paying user** is `windows.<code>.cac`, and the two differ by the entire install→payer funnel. Quoting one as the other overstates efficiency by an order of magnitude on most accounts.
</Warning>

### Closed maturation windows

Row-level `revenue`/`roas` are cumulative **to date**: revenue keeps accruing while spend is bounded by the period, so they cannot compare cohorts of different ages. Request `windows` (`d0`, `d7`, `d30`, … `lifetime`) and every row gains a block computed only over install dates that have fully matured.

* `is_closed: false` means the numbers cover a closed **subrange** — `[closed_from, closed_through]`, not `[from, to]`. They are provisional, and the ratios can move in either direction. Say the window is still maturing and name `closed_through`.
* `d0` means **through the end of the install UTC day**, not the first 24 hours from the install moment.
* `lifetime` never closes, by definition.
* `null` is not zero. A missing ratio means "not available yet"; a `spend_closed: 0` is a measured zero.
* A date is only final once it is past both the window length plus the buffer **and** the restatement floor (`meta.windows.spend_snapshot.rewrite_days_effective`) — the store rewrites its most recent days, and no date is called final while that can still happen.

### Markers to check before quoting anything

`partial_sources` (the Apple side degraded — affected rows have `apple: null`), `meta.partial_scope` (how many campaigns lack spend), `meta.is_partial_period` (the range includes today), `meta.windows.spend_snapshot` (three distinct states: normal, still backfilling, read failed), and `meta.request.filters_applied` — which lists only the filters that were **recognised**, so check it before assuming a filter took effect.

## Reading the series

`get_apple_ads_series` plots one metric per UTC day.

<Warning>
  **Do not loop the report to build a time series.** The report's cohort metrics are cumulative to date from each install date; a series point is the value attributed to *that* day. The two answer different questions and return different numbers.
</Warning>

* `value: null` is **unknown** (outside the spend snapshot's coverage, missing from it, or an empty denominator), never zero.
* `is_cohort_metric: true` means the point belongs to the cohort **acquired** that day — revenue on 3 March is "what the people acquired on 3 March have paid to date", not revenue collected on 3 March.
* `filters_ignored` lists filters that were accepted and not applied (the entity-state filters have no meaning on a time axis). Non-empty means your numbers answer a wider question than you asked.

## Checking the connection

`get_apple_ads_connection_status` exists because an empty report and a refused change look identical whether the cause is "no data yet", "the Apple authorization expired" or "this Apple role cannot write". Call it before concluding anything from either.

It returns two **independent** readiness axes:

* `reporting` — whether performance data can flow.
* `campaign_management` — whether changes are allowed, with `can_write`, the per-`orgs[]` detail, and the exact Apple role names.

`connected` therefore does **not** imply write access; the ordinary case is a perfectly working integration whose Apple role only reads. Other states worth naming precisely:

| State                                | What it means                                                                                                                                                             |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy_credentials`                 | Connected with an older customer key. Everything works; migrating is a recommendation, not a fault.                                                                       |
| `verifying`                          | The authorization is stored, Apple has not confirmed it yet. Not "connected and verified".                                                                                |
| `campaign_management.state: unknown` | Apple's daily snapshot of your roles has not landed, or is too old to be evidence. "Ask again later" — never "you are not allowed".                                       |
| Several `orgs[]`                     | Not a blocker and never a reason to reconnect. Management is available if at least one org allows it; the specific change is authorized against the org of that campaign. |

The response never contains a private key, client secret, token, authorization code or OAuth state — and the tool cannot start the sign-in flow. It returns `dashboard_url` instead, which is where a human completes it. **Never paste a `.p8` key or a client secret into a chat.**

## Changing campaigns

The write tools require the separate `apple_ads:write` scope **and** a dashboard user who is allowed to manage campaigns. A project Secret Key on its own is refused: that key authorizes the whole public API and tends to live in CI variables, while the right to spend money is granted per member in the dashboard.

<Warning>
  These tools change a live Apple Ads account and spend real money. Read the report first: you need the entity ids **and** the current value, because the current value is mandatory.
</Warning>

### The rules

* **`before_*` is required.** It is the optimistic lock (a `409` means the value changed under you — re-read the report, do not retry), the source an undo would use, and the sign of the spend change that the daily caps count.
* **One action per request**: a status, a bid, or a daily budget — never two.
* **Confirmation is asymmetric.** Pausing an entity or lowering a value applies immediately. Enabling one or raising a value is parked for human confirmation via [`confirm_destructive_action`](/docs/mcp-server#destructive-actions) — the token is addressed to the operator, not a cue for the assistant to confirm its own request.
* **`idempotency_key`** makes a retry the same attempt rather than a second change. Omit it and one is generated for this attempt; pass the same one back when retrying after an unknown outcome.
* **`dry_run: true`** changes nothing and returns `would_send`, the exact payload Apple would have received. Use it before any first-time or unusual change.
* **Amounts are decimal strings** in the **advertising account's** currency — never the currency you requested a report in, and never converted.

### Outcomes that must be handled differently

| Result        | What to do                                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `409`         | The value changed under you, or the idempotency key was reused with a different body. Re-read the report; do not retry the same body. |
| `422`         | The request cannot be executed. The message names what to change.                                                                     |
| `429`         | A rate limit or a daily cap on spend-increasing actions. `Retry-After` says how long; a daily cap does not clear within the minute.   |
| `502` / `504` | The outcome is **unknown** — the change may or may not have reached Apple. Read the report to see what happened. Never retry blindly. |

A success carries `action_id` (the audit row — name it when describing what you did). If it also carries `baseline_unverified: true`, there was no confirmed history for that entity, the ×3 raise ceiling could not be applied, and a human should look at the result.

### The bid you read back may be stale

Bids and budgets in a report row come from Apple's reporting metadata and can lag by hours — including behind a change you just made yourself. Confirm a write from the write's own response, not by re-reading the report a second later.

## Rate limits

Analytics tools are limited to 30 requests per minute, counted per project and per identical request. Over the limit you get a `429` with `Retry-After` — never a cached answer pretending to be fresh. Write actions have their own tighter limits plus daily caps on spend-increasing changes.


# MCP Server
Source: https://documentation.qonversion.io/docs/mcp-server

Connect AI assistants to your Qonversion project data via the Model Context Protocol

<Note>
  The Qonversion MCP server is currently in **beta**. Tool names, arguments, and OAuth scopes may still change. Not recommended for production-critical workflows yet — we'd love your feedback while we stabilise it.
</Note>

Qonversion provides a remote MCP server that allows AI assistants to access your project data. The server is hosted at `https://mcp.qonversion.io/mcp` and uses OAuth 2.1 for authentication.

The server follows the [MCP Streamable HTTP spec](https://modelcontextprotocol.io/specification/2025-03-26) and supports clients that connect natively over HTTP, as well as clients that use [`mcp-remote`](https://github.com/geelen/mcp-remote) for compatibility.

<Note>
  The MCP server mirrors the [Qonversion REST API v4](/reference/v4/overview) resource surface — each MCP tool corresponds to a v4 operation. Authentication is different, though: HTTP clients authenticate with the project Secret Key, while MCP clients use OAuth 2.1 against your Qonversion account with per-tool scopes. See the full [v4 guide](/reference/v4/overview) for resource-by-resource context, or the [API Reference](/api-reference/rest-api-v4) for the underlying HTTP operations.
</Note>

## Capabilities

The Qonversion MCP server exposes the full surface of the v4 REST API as MCP tools, grouped by resource:

* **Customers** — list, read, delete (GDPR), set properties, list and mutate permissions, and read aggregated metrics.
* **Users, identities, purchases, properties** — look up users, attach external identities, inspect purchase history, set and query user properties.
* **Entitlements** — manage entitlement definitions and grant or revoke them per user.
* **Products** — CRUD products consumed by the SDK.
* **Remote Configurations** — list, create, replace, delete, change status, manage payload mappings, and attach or detach users.
* **Paywalls (Screens)** — list, create, update, publish, duplicate, and pull per-screen and overview analytics.
* **Experiments** — CRUD experiments and groups, change status, attach and detach users, read summary analytics.
* **Segments** — CRUD user segments and list system segments.
* **Analytics** — charts, KPI cards, cohorts, LTV, trial conversion, currencies, and narrative insights.
* **Apple Ads** (closed beta) — cohort performance joined with Apple Search Ads spend, the daily series behind it, connection status, and campaign management (pause/enable, bids, daily budgets). Campaign changes need the separate `apple_ads:write` scope. See [Apple Ads via MCP](/docs/mcp-apple-ads).
* **Exports** — start asynchronous data exports and poll their history and status.
* **Events** — inspect the event catalog and the raw event log.
* **Scheduled Reports** — CRUD recurring reports, list destinations, send a test delivery.
* **Integrations** — discover the catalog, create, toggle status, and delete integrations.
* **Automations** — CRUD event-driven automations and change their status.
* **Project settings** — read and update project configuration, rotate the Secret Key, manage store credentials.

The MCP server does **not** use Project or Secret API keys. Authentication is OAuth 2.1 against your Qonversion account, and access to each tool is gated by the OAuth scopes granted during the login flow (e.g., `customers:read`, `screens:read`, `experiments:write`). Your effective permissions mirror your role in the Qonversion dashboard.

## Destructive actions

Destructive tools (`delete_*`, `revoke_*`, `detach_*`, `regenerate_project_secret`) use a two-step confirmation flow designed around **human-in-the-loop** intent. The confirmation token is addressed to the operator, not to the agent — the agent is expected to surface the pending action and wait for explicit approval before executing.

### The flow

1. The agent calls the destructive tool (e.g., `delete_product(product_id: "prem_monthly")`).
2. The server **does not** perform the action. It returns a message listing the pending action, the target **Resource id**, and a short-lived **token** (5-minute TTL). The message is explicitly addressed to the human operator.
3. The agent must surface the pending action to the human and wait for explicit approval.
4. Once approved, the agent calls `confirm_destructive_action` with three required arguments:

| Field              | Type   | Notes                                                                                                                      |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `token`            | string | The opaque token from step 2                                                                                               |
| `resource_id_echo` | string | Must match the **Resource id** verbatim (case-sensitive). A mismatch cancels the pending action and returns a typed error. |
| `reason`           | string | Short justification, 1-256 characters. Captured in the audit log.                                                          |

### Why the echo + reason

These two fields turn a single-turn `delete → confirm` chain into an act of deliberate re-statement. The agent can't forward the token blindly — it has to restate the target (which surfaces the action to the human) and commit a reason (which is easy to spot in review if fabricated). Silent auto-confirmation stops being possible without the model making a distinct act that's visible in the transcript.

### Tokens

* Tokens are bound to the MCP session that requested them — another session can't consume them.
* Tokens expire after 5 minutes. Expired tokens must be re-requested from the original tool.
* A token can be used at most once. A mismatched `resource_id_echo` consumes the token and cancels the pending action.
* Tokens are **not** logged in the audit trail; the resource id and reason are.

### Destructive tools affected

`delete_automation`, `delete_customer`, `delete_entitlement`, `delete_experiment`, `delete_experiment_group`, `delete_integration`, `delete_product`, `delete_remote_configuration`, `delete_scheduled_report`, `delete_screen`, `delete_segment`, `detach_experiment_user`, `detach_user_from_remote_configuration`, `revoke_customer_permission`, `revoke_user_entitlement`, `regenerate_project_secret`.

## Setup

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "Qonversion": {
      "type": "streamable-http",
      "url": "https://mcp.qonversion.io/mcp"
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add --transport http Qonversion https://mcp.qonversion.io/mcp
```

Run `/mcp` in a Claude Code session to go through the authentication flow.

### Cursor

Add the following to your `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "Qonversion": {
      "url": "https://mcp.qonversion.io/mcp"
    }
  }
}
```

### Visual Studio Code

1. Press `CTRL/CMD + P` and search for **MCP: Add Server**.
2. Select **Command (stdio)**.
3. Enter the following and press enter:

```
npx mcp-remote https://mcp.qonversion.io/mcp
```

4. Enter the name **Qonversion** and press enter.
5. Open **MCP: List Servers**, select **Qonversion**, and click **Start Server**.

### Windsurf

1. Press `CTRL/CMD + ,` to open settings.
2. Go to Cascade → MCP servers.
3. Select **Add Server → Add custom server** and add the following:

```json theme={null}
{
  "mcpServers": {
    "Qonversion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.qonversion.io/mcp"]
    }
  }
}
```

### Zed

1. Press `CMD + ,` to open settings.
2. Add the following:

```json theme={null}
{
  "context_servers": {
    "Qonversion": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.qonversion.io/mcp"],
      "env": {}
    }
  }
}
```

### Codex

Add the following to your `~/.codex/config.toml`:

```toml theme={null}
[features]
experimental_use_rmcp_client = true

[mcp_servers.Qonversion]
url = "https://mcp.qonversion.io/mcp"
```

Run `codex mcp login Qonversion` to authenticate.

### Other clients

For clients that support MCP via stdio, use the following configuration:

* **Command**: `npx`
* **Arguments**: `-y mcp-remote https://mcp.qonversion.io/mcp`
* **Environment**: None

## Authentication

On the first connection, your MCP client will open a browser window to authenticate with your Qonversion account. No manual configuration of tokens or API keys is required.


# Migrate Offerings to Remote Configs
Source: https://documentation.qonversion.io/docs/migrate-offerings-to-remote-configs

Move your paywall product management from legacy Offerings to Remote Configs

<Info>
  Your existing Offerings keep working. The `offerings` SDK method and the data behind it will continue to be served, so paywalls in already-shipped app versions are not affected. This guide is for moving new development and day-to-day paywall management to Remote Configs. The Offerings dashboard section stays available in projects that already have offerings.
</Info>

Offerings were designed to solve one problem: changing the set of products on a paywall without an app release. [Remote Configs](remote-config) solve the same problem as part of a more capable tool, and have replaced Offerings for all new integrations. On top of what Offerings could do, Remote Configs give you:

* **Any payload, not just products** — manage the whole paywall (products, texts, colors, layout flags) with one config.
* **Targeting** — serve different product sets by country, store, app version, subscription status, or purchase history. [See segmentation options](remote-config#5-segment-users).
* **A/B testing** — [launch an experiment directly from a config](launch-test-from-remote-config).
* **Drafts and safe rollout** — prepare changes without publishing them, [test on your own device before launch](remote-config#4-test-changes-before-launch).

## Concept mapping

| Offerings concept             | Remote Configs equivalent                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Offering ID (e.g. `discount`) | Context key (e.g. `discount_paywall`)                                                                                                                  |
| Product list and its order    | An array of product IDs in the JSON payload                                                                                                            |
| Main offering                 | The context key your app requests by default (e.g. `main_paywall`)                                                                                     |
| `offerings()` SDK method      | [`remoteConfig(contextKey)`](remote-config#3-integrate-changes-into-your-app) + [`products()`](displaying-products#get-the-list-of-available-products) |

## 1. Create a Remote Config with your products

Open [Remote Configs](https://dash.qonversion.io/remote-configs) and create a configuration for each offering you actively manage. Use the offering ID as the context key (or pick a clearer name — the key is yours), and put the product IDs into the payload in the order you want to display them:

```json theme={null}
{
  "products": ["weekly_premium", "annual_premium_trial"]
}
```

The payload is plain JSON, so you decide on the structure. `products` is just a convention that keeps this guide simple — you can add any other paywall settings next to it later.

<Frame>
  <img />
</Frame>

## 2. Read the config in your app

Request the config by its context key, then resolve the product IDs to store products with the `products` method:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig(contextKey: "main_paywall") { remoteConfig, error in
      guard let payload = remoteConfig?.payload,
            let productIds = payload["products"] as? [String] else { return }

      Qonversion.shared().products { allProducts, error in
          let paywallProducts = productIds.compactMap { allProducts[$0] }
          // Display paywallProducts in the configured order
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig("main_paywall", object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          val productIds = (remoteConfig.payload["products"] as? List<*>)
              ?.filterIsInstance<String>() ?: return

          Qonversion.shared.products(object : QonversionProductsCallback {
              override fun onSuccess(products: Map<String, QProduct>) {
                  val paywallProducts = productIds.mapNotNull { products[it] }
                  // Display paywallProducts in the configured order
              }

              override fun onError(error: QonversionError) { /* handle error */ }
          })
      }

      override fun onError(error: QonversionError) { /* handle error */ }
  })
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: 'main_paywall');
  final productIds = List<String>.from(remoteConfig.payload['products'] as List);

  final products = await Qonversion.getSharedInstance().products();
  final paywallProducts = productIds
      .map((id) => products[id])
      .whereType<QProduct>()
      .toList();
  // Display paywallProducts in the configured order
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('main_paywall');
  const productIds: string[] = remoteConfig.payload['products'] ?? [];

  const products = await Qonversion.getSharedInstance().products();
  const paywallProducts = productIds
    .map((id) => products.get(id))
    .filter((product) => product != null);
  // Display paywallProducts in the configured order
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig("main_paywall", (remoteConfig, error) =>
  {
      if (error != null) return;
      var productIds = remoteConfig.Payload["products"] as List<object>;

      Qonversion.GetSharedInstance().Products((products, productsError) =>
      {
          if (productsError != null) return;
          // Pick products by the IDs from the payload and display them
      });
  });
  ```
</CodeGroup>

If your app used `offerings().main`, request your default context key (e.g. `main_paywall`) in the same place. If it used `offering(forIdentifier:)`, request the corresponding context key instead.

## 3. Test before launch

Attach your test device to the new configuration with `attachUserToRemoteConfiguration` and verify the paywall renders the right products — see the [testing guide](remote-config#4-test-changes-before-launch).

## 4. Roll out

Ship the app update that reads Remote Configs. From that point, manage your paywall products in the Remote Configs section.

Keep your existing Offerings untouched while app versions that read them still have an audience — the data keeps being served to them. There is no forced cut-off date. Once traffic from those versions fades out, the offerings can simply be deleted.

***

What's Next

* [Create Remote Config](remote-config)
* [Launch A/B test from Remote Config](launch-test-from-remote-config)


# [Dec 2022] Migration Guide
Source: https://documentation.qonversion.io/docs/migrate-to-the-actual-qonversion-sdk-version-december-2022

We have released a major update for our Qonversion SDK with several new features, improvements, and design fixes. This article provides the necessary steps to migrate from previous SDK versions to the ones displayed in the table below:

| Platform     | Major version |
| ------------ | ------------- |
| iOS          | 3.+           |
| Android      | 4.+           |
| Flutter      | 5.+           |
| React Native | 4.+           |
| Unity        | 4.+           |

Choose your platform to continue:

* [iOS 3.+ migration guide](ios-3-migration-guide)
* [Android 4.+ migration guide](android-4-migration-guide)
* [Flutter 5.+ migration guide](flutter-5-migration-guide)
* [React Native 4.+ migration guide](react-native-4-migration-guide)
* [Unity 4.+ migration guide](unity-4-migration-guide)

***

[Web 1.+ migration guide](web-1-migration-guide)

[iOS 3.+ migration guide](ios-3-migration-guide)


# Migrating from RevenueCat
Source: https://documentation.qonversion.io/docs/migrating-from-revenuecat-to-qonversion

We have prepared this guide to help you move your infrastructure seamlessly from RevenueCat to Qonversion. Although this guide is comprehensive and should enable you to transfer the entire infrastructure smoothly, feel free to reach out to support if you have any questions.

1. [Configure dashboard](#configure-dashboard)
2. [Install SDKs](#install-sdks)
3. [User-base migration](#user-base-migration)

## Configure dashboard

First and foremost, [register](https://go.qonversion.io/Ouf6) at Qonversion. Registration will take you through an onboarding process, where you'll have to fill out information about your project and insert links — all to help you add your project to Qonversion. We highly recommend following this flow and not skipping any settings during registration. We'll also cover the scenario if you don't fill these out.

### Store Settings

First, let's set up your Stores in the Qonversion dashboard. To do this, gather the necessary data from RevenueCat.

#### Apple App Store settings

To configure the Apple App Store in Qonversion, you will need the following fields:

1. **App-Specific Shared Secret**: Copy this value from the App Store Connect App-specific Shared Secret field in the App Settings app settings in the RevenueCat dashboard. See the screen below. [Here's](ios-app-store-info-fields#2-generate-the-app-specific-shared-secret) a more detailed guide on how to obtain this.
2. **App Store ID**: You'll find your App Store ID in the URL of your App Store Connect account. For example, if your URL is something like `https://apps.apple.com/us/app/example-app/id123456789`, then 123456789 is your app's Apple ID.

<img alt="" />

#### Google Play Console Settings

Here's what you have in RevenueCat:

<img alt="" />

To set up your Google Play account in Qonversion, you will need the following:

1. **Android Package Name**: This is the applicationID found in your app-level build.gradle file. You can either copy it from there or use the **Google play package** from your RevenueCat settings.
2. **Service Account Credentials JSON**: attach the same file you used for **Service Account Credentials JSON** at RevenueCat. [Here's more](android-store-setup) on how you can get Google Play Service Account Key.

<Check>
  ### Configure Stores in Qonversion

  Once you have all the necessary data from RevenueCat, follow the steps to set up Stores in Qonversion
</Check>

[Stores Settings](https://demo.arcade.software/Eq6Y1v6okCVCUhOcYfUF?embed\&embed_mobile=inline\&embed_desktop=inline\&show_copy_link=true)

### Products, Entitlements and Remote Configs

After you've filled the store data, it's time to set up Products, Entitlements, and Remote Configs. Here's another way to describe these elements:

| RevenueCat   | Qonversion     |
| ------------ | -------------- |
| Entitlements | Entitlements   |
| Packages     | Products       |
| Offerings    | Remote Configs |

#### Entitlements

Let's start with Entitlements. Similar to how you set up Entitlements in RevenueCat, you need to set up Entitlements in Qonversion.

Here's how it was done in RevenueCat:

<img alt="" />

Here's how to do it in Qonversion:

Navigate to the Entitlements and click the **Create Entitlement** button.

[Create entitlements](https://demo.arcade.software/dYOIEanZRhOmQ9zidazH?embed\&embed_mobile=inline\&embed_desktop=inline\&show_copy_link=true)

#### Products

Next, you need to create Products similar to how you created in RevenueCat:

<img alt="" />

To create Products in Qonversion, go to **Entitlements → Products** and click **Create Product**.

[Entitlements – Products](https://demo.arcade.software/Evi7fa9nT4xmjzuavh4j?embed\&embed_mobile=inline\&embed_desktop=inline\&show_copy_link=true)

* **Qonversion Product ID** is your unique product identifier in Qonversion that corresponds to a unique product on the Apple App Store and Google Play Store. Qonversion SDK will use it to make purchases.

* **AppStore Product ID** – product identifier on Apple App Store. Learn more on how to create [subscriptions on iOS](https://qonversion.io/blog/configure-iap-app-store-connect/).

* **Google Play Product ID** – product identifier on Google Play Console. Learn more on how to set up [Android in-app products ](android-in-app-products).

* **Google Play Base Plan ID** - identifier of the base plan for Google Play Product. This is used for subscription products. If you're creating an in-app, leave this field empty for in-apps. In Qonversion, you will set up different products for the different base plans of the same product.

* **Associated Entitlements** - choose the entitlements that should be granted once this product is purchased.

#### Remote Configs (instead of RevenueCat Offerings)

In RevenueCat, Offerings define which products are presented on a paywall. In Qonversion, this is covered by [Remote Configs](remote-config): create a configuration with a context key (e.g. `main_paywall`) and put your product IDs into the JSON payload in the order you want to display them:

```json theme={null}
{
  "products": ["weekly_premium", "annual_premium_trial"]
}
```

<Frame>
  <img />
</Frame>

Beyond changing products without an app release, Remote Configs also let you [target user segments](remote-config#5-segment-users) and [run A/B tests](launch-test-from-remote-config). See [the payload convention and code samples](migrate-offerings-to-remote-configs) for details.

### Server-to-server notifications

To seamlessly implement server-to-server notifications, use RevenueCat S2S URLs as a temporary proxy in our system. This allows Qonversion to process new requests while still sending notifications to your existing users.

#### Configure Apple App Store

1. Navigate to your Qonversion [project settings](https://dash.qonversion.io/project-settings/stores?tab=ios). Copy the server-to-server notification URL for Apple App Store.
2. Sign in to [App Store Connect](https://appstoreconnect.apple.com/apps) and select your app.
3. Navigate to the App Information section.

<img alt="" />

4. Copy the RevenueCat URL you used for server-to-server notifications and replace it with the URL from step 1.
5. Set up the RevenueCat URL as a Proxy URL in Qonversion in [project settings](https://dash.qonversion.io/project-settings/stores?tab=ios).

See more information [here](ios-s2s-notifications).

#### Google Developer Notifications

1. [Enable access to API here](https://console.cloud.google.com/flows/enableapi?apiid=pubsub).

   <img alt="" />

2. Navigate to [project settings](https://dash.qonversion.io/project-settings/stores?tab=android), then click the "Connect to Google" button.

3. You need to copy generated **Google Developer Notifications Topic ID**.

4. Open the **Google Play Console** for your application, then navigate to **Monetization setup**.

5. In the **Real-time developer notifications** tab, insert your topic ID, click on **Save changes**, and then the **Send Test Notification** button.

It takes up to 24 hours for your [Google service credentials](android-store-setup) to work correctly. Make sure to wait for at least 24 hours after you have created the credentials before connecting to Google Real-Time Developer Notifications.

See more information [here](google-developer-notifications).

## Install SDKs

Check out the links below for the SDK you need and follow the steps provided:

→ [iOS SDK](ios-sdk-setup) → [Android SDK](android-sdk) → [Flutter SDK](flutter-sdk) → [React Native SDK](react-native-sdk) → [Unity SDK](unity-sdk) → [Cordova Plugin](cordova) → [Capacitor Plugin](capacitor) → [Web](web-sdk) → [Kids Mode Qonversion SDKs](kids-mode-sdk)

Read more about [Installing the SDKs](install-sdk).

When you're done with the setup, it's time to get into the code!

### Launch SDK

Firstly, you need to initialize the SDK. Here's how you did it in RevenueCat:

<CodeGroup>
  ```swift Swift theme={null}
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

      Purchases.logLevel = .debug
      Purchases.configure(withAPIKey: <public_apple_api_key>, appUserID: <app_user_id>)

  }
  ```

  ```objectivec Objective-C theme={null}
  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    	// Override point for customization after application launch.

    	RCPurchases.logLevel = RCLogLevelDebug;
          [RCPurchases configureWithAPIKey:<public_apple_api_key> appUserID:<app_user_id>];

    	return YES;
  }
  ```

  ```java Java theme={null}
  public class App extends Application {
    @Override
    public void onCreate() {
      super.onCreate()
      Purchases.setDebugLogsEnabled(true);
      Purchases.configure(new PurchasesConfiguration.Builder(this, <public_google_api_key>).build());
    }
  }
  ```

  ```kotlin Kotlin theme={null}
  class App : Application() {
    override fun onCreate() {
      super.onCreate()
      Purchases.debugLogsEnabled = true
      Purchases.configure(PurchasesConfiguration.Builder(this, <public_google_api_key>).build())
    }
  }
  ```

  ```dart Flutter theme={null}
  import 'dart:io' show Platform;

  //...

  Future<void> initPlatformState() async {
    await Purchases.setDebugLogsEnabled(true);

    PurchasesConfiguration configuration = PurchasesConfiguration(<public_api_key>);
    await Purchases.configure(configuration);
  }
  ```

  ```typescript React Native theme={null}
  Purchases.setLogLevel(Purchases.LOG_LEVEL.DEBUG);
  await Purchases.configure({ apiKey: <public_api_key> });
  ```

  ```csharp Unity theme={null}
  Purchases.PurchasesConfiguration.Builder builder = Purchases.PurchasesConfiguration.Builder.Init(<public_api_key>);
  Purchases.PurchasesConfiguration purchasesConfiguration =
      .SetAppUserId(<app_user_id>)
      .Build();
  purchases.Configure(purchasesConfiguration);
  ```

  ```typescript Cordova theme={null}
  document.addEventListener("deviceready", onDeviceReady, false);

  function onDeviceReady() {
      Purchases.setDebugLogsEnabled(true);
    	Purchases.configureWith({ apiKey: <public_api_key> });
  }
  ```

  ```typescript Capacitor theme={null}
  const onDeviceReady = async () => {
      await Purchases.setLogLevel({level: LOG_LEVEL.DEBUG});
      if (Capacitor.getPlatform() === 'ios') {
          await Purchases.configure({ apiKey: <public_apple_api_key> });
      } else if (Capacitor.getPlatform() === 'android') {
          await Purchases.configure({ apiKey: <public_google_api_key> });
      }
  }
  ```
</CodeGroup>

Here's how you'll do it for Qonversion — request the Remote Config holding your product IDs, then resolve them to store products:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig(contextKey: "main_paywall") { remoteConfig, error in
      guard let payload = remoteConfig?.payload,
            let productIds = payload["products"] as? [String] else { return }

      Qonversion.shared().products { allProducts, error in
          let paywallProducts = productIds.compactMap { allProducts[$0] }
          // Display paywallProducts in the configured order
      }
  }
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig("main_paywall", object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          val productIds = (remoteConfig.payload["products"] as? List<*>)
              ?.filterIsInstance<String>() ?: return

          Qonversion.shared.products(object : QonversionProductsCallback {
              override fun onSuccess(products: Map<String, QProduct>) {
                  val paywallProducts = productIds.mapNotNull { products[it] }
                  // Display paywallProducts in the configured order
              }

              override fun onError(error: QonversionError) { /* handle error */ }
          })
      }

      override fun onError(error: QonversionError) { /* handle error */ }
  })
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: 'main_paywall');
  final productIds = List<String>.from(remoteConfig.payload['products'] as List);

  final products = await Qonversion.getSharedInstance().products();
  final paywallProducts = productIds
      .map((id) => products[id])
      .whereType<QProduct>()
      .toList();
  // Display paywallProducts in the configured order
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('main_paywall');
  const productIds: string[] = remoteConfig.payload['products'] ?? [];

  const products = await Qonversion.getSharedInstance().products();
  const paywallProducts = productIds
    .map((id) => products.get(id))
    .filter((product) => product != null);
  // Display paywallProducts in the configured order
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig("main_paywall", (remoteConfig, error) =>
  {
      if (error != null) return;
      var productIds = remoteConfig.Payload["products"] as List<object>;

      Qonversion.GetSharedInstance().Products((products, productsError) =>
      {
          if (productsError != null) return;
          // Pick products by the IDs from the payload and display them
      });
  });
  ```
</CodeGroup>

[See the full guide: products via Remote Configs](migrate-offerings-to-remote-configs)

### Making purchases

RevenueCat:

<CodeGroup>
  ```swift Swift theme={null}
  Purchases.shared.purchase(package: package) { (transaction, customerInfo, error, userCancelled) in
    if customerInfo.entitlements["your_entitlement_id"]?.isActive == true {
      // Unlock that great "pro" content
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[RCPurchases sharedPurchases] purchasePackage:package withCompletion:^(RCStoreTransaction *transaction, RCCustomerInfo *customerInfo, NSError *error, BOOL cancelled) {
    if (customerInfo.entitlements[@"your_entitlement_id"].isActive) {
      // Unlock that great "pro" content
    }
  }];
  ```

  ```java Java theme={null}
  Purchases.getSharedInstance().purchase(
  	new PurchaseParams.Builder(this, aPackage).build(),
  	new PurchaseCallback() {
      @Override
      public void onCompleted(@NonNull StoreTransaction storeTransaction, @NonNull CustomerInfo customerInfo) {
  			if (customerInfo.getEntitlements().get(<my_entitlement_identifier>).isActive()) {
  				// Unlock that great "pro" content
  			}
  		}

  		@Override
  		public void onError(@NonNull PurchasesError purchasesError, boolean b) {
  			// No purchase
  		}
  	}
  );
  ```

  ```kotlin Kotlin theme={null}
  Purchases.sharedInstance.purchaseWith(
    PurchaseParams.Builder(this, aPackage).build(),
    onError = { error, userCancelled -> /* No purchase */ },
    onSuccess = { storeTransaction, customerInfo ->
      if (customerInfo.entitlements["my_entitlement_identifier"]?.isActive == true) {
        // Unlock that great "pro" content
      }
    }
  )
  ```

  ```dart Flutter theme={null}
  try {
    CustomerInfo customerInfo = await Purchases.purchasePackage(package);
    if (customerInfo.entitlements.all["my_entitlement_identifier"].isActive) {
      // Unlock that great "pro" content
    }
  } on PlatformException catch (e) {
    var errorCode = PurchasesErrorHelper.getErrorCode(e);
    if (errorCode != PurchasesErrorCode.purchaseCancelledError) {
      showError(e);
    }
  }
  ```

  ```typescript React Native theme={null}
  try {
    const { customerInfo } = await Purchases.purchasePackage(package);
    if (
      typeof customerInfo.entitlements.active["my_entitlement_identifier"] !==
      "undefined"
    ) {
      // Unlock that great "pro" content
    }
  } catch (e) {
    if (!e.userCancelled) {
      showError(e);
    }
  }
  ```

  ```csharp Unity theme={null}
  Purchases purchases = GetComponent<Purchases>();
  purchases.PurchasePackage(package, (productIdentifier, customerInfo, userCancelled, error) =>
  {
    if (customerInfo.Entitlements.Active.ContainsKey("my_entitlement_identifier")) {
      // Unlock that great "pro" content
    }
  });
  ```

  ```typescript Cordova theme={null}
  Purchases.purchasePackage(package, ({ productIdentifier, customerInfo }) => {
      if (typeof customerInfo.entitlements.active.my_entitlement_identifier !== "undefined") {
        // Unlock that great "pro" content
      }
    },
    ({error, userCancelled}) => {
      // Error making purchase
    }
  );
  ```

  ```typescript Capacitor theme={null}
  try {
    const purchaseResult = await Purchases.purchasePackage({ aPackage: packageToBuy });
    if (typeof purchaseResult.customerInfo.entitlements.active['my_entitlement_identifier'] !== "undefined") {
      // Unlock that great "pro" content
    }
  } catch (error: any) {
    if (error.code === PURCHASES_ERROR_CODE.PURCHASE_CANCELLED_ERROR) {
      // Purchase cancelled
    } else {
      // Error making purchase
    }
  }
  ```
</CodeGroup>

Qonversion:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().purchase(product) { (result) in
    if result.isSuccessful {
      if let premium: Qonversion.Entitlement = result.entitlements["premium"], premium.isActive {
        // Grant user access to premium features
      }
    } else if result.isCanceledByUser {
      // Handle canceled purchase
    } else if result.isPending {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
    if (result.isSuccessful) {
      QONEntitlement *premiumEntitlement = result.entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        // Grant user access to premium features
      }
    } else if (result.isCanceledByUser) {
      // Handle canceled purchase
    } else if (result.isPending) {
      // Handle pending purchase
    } else {
      // Handle errors
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().purchase(this, product, new QonversionPurchaseCallback() {
      @Override
      public void onResult(@NonNull QPurchaseResult result) {
          if (result.isSuccessful()) {
              QEntitlement premium = result.getEntitlements().get("premium");
              if (premium != null && premium.isActive()) {
                  // Grant user access to premium features
              }
          } else if (result.isCanceledByUser()) {
              // Handle canceled purchase
          } else if (result.isPending()) {
              // Handle pending purchase
          } else {
              // Handle errors
          }
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.purchase(this, product, object : QonversionPurchaseCallback {
      override fun onResult(result: QPurchaseResult) {
          when {
              result.isSuccessful -> {
                  val premium = result.entitlements["premium"]
                  if (premium != null && premium.isActive) {
                      // Grant user access to premium features
                  }
              }
              result.isCanceledByUser -> {
                  // Handle canceled purchase
              }
              result.isPending -> {
                  // Handle pending purchase
              }
              else -> {
                  // Handle errors
              }
          }
      }
  })
  ```

  ```dart Flutter theme={null}
  final result = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    final premium = result.entitlements?['premium'];
    if (premium != null && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript React Native theme={null}
  const result: PurchaseResult = await Qonversion.getSharedInstance().purchaseWithResult(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Purchase(product, (result) =>
  {
      if (result.IsSuccess)
      {
          if (result.Entitlements != null &&
              result.Entitlements.TryGetValue("premium", out var premium) &&
              premium.IsActive)
          {
              // Grant user access to premium features
          }
      }
      else if (result.IsCanceled)
      {
          // Handle canceled purchase
      }
      else if (result.IsPending)
      {
          // Handle pending purchase
      }
      else
      {
          // Handle errors
      }
  });
  ```

  ```typescript Cordova theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```

  ```typescript Capacitor theme={null}
  const result = await Qonversion.getSharedInstance().purchase(product);

  if (result.isSuccess) {
    const premium = result.entitlements?.get('premium');
    if (premium && premium.isActive) {
      // Grant user access to premium features
    }
  } else if (result.isCanceled) {
    // Handle canceled purchase
  } else if (result.isPending) {
    // Handle pending purchase
  } else {
    // Handle errors
  }
  ```
</CodeGroup>

### Restore purchases

If your app has a restore purchases feature on paywalls, just use the Qonversion `restore()` function when users want to restore their purchases.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().restore { [weak self] (entitlements, error) in
    if let error = error {
      // Handle error
    }

    if let entitlement: Qonversion.Entitlement = entitlements["plus"], entitlement.isActive {
      // Restored and entitlement is active
    }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] restore:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull result, NSError * _Nullable error) {
    if (error) {
      // Handle error
    }
    QONEntitlement *entitlement = result[@"active"];
    if (entitlement && entitlement.isActive) {
      // Restored and entitlement is active
    }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().restore(new QonversionEntitlementsCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
          QEntitlement premiumEntitlement = entitlements.get("premium");

          if (premiumEntitlement != null && premiumEntitlement.isActive()) {
              // handle active entitlement here
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.restore(object : QonversionEntitlementsCallback {
      override fun onSuccess(entitlements: Map<String, QEntitlement>) {
          val premiumEntitlement = entitlements["premium"]
          if (premiumEntitlement != null && premiumEntitlement.isActive) {
              // handle active entitlement here
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().restore();
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
    const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().restore();
   } catch (e) {
    console.log(e);
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Restore((entitlements, error) =>
  {
        if (error == null)
        {
           // Handle entitlements here
        }
        else
        {
          // Handle the error
          Debug.Log("Error" + error.ToString());
        }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await Qonversion.getSharedInstance().restore();
  } catch (e) {
      console.log(e);
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().restore();
   } catch (e) {
    console.log(e);
  }
  ```
</CodeGroup>

### User status

To check the customer status in Qonversion, you need to use Entitlements. In RevenueCat, you used Customer info and entitlements.

RevenueCat:

<CodeGroup>
  ```swift Swift theme={null}
  Purchases.shared.getCustomerInfo { (customerInfo, error) in
      // access latest customerInfo
  		if customerInfo.entitlements[<your_entitlement_id>]?.isActive == true {
    			// user has access to "your_entitlement_id"
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[RCPurchases sharedPurchases] customerInfoWithCompletion:^(RCCustomerInfo * customerInfo, NSError * error) {
      // access latest customerInfo
    	if (customerInfo.entitlements[@<your_entitlement_id>].isActive) {
   				// user has access to "your_entitlement_id"
  		}
  }];
  ```

  ```kotlin Kotlin theme={null}
  Purchases.sharedInstance.getCustomerInfo({ error -> /* Optional error handling */ }) { customerInfo ->
  	  // access latest customerInfo
  	  if (customerInfo.entitlements[<your_entitlement_id>]?.isActive == true) {
  				// user has access to "your_entitlement_id"
  		}
  }
  ```

  ```java Java theme={null}
  Purchases.getSharedInstance().getCustomerInfo(new ReceiveCustomerInfoCallback() {
  	  @Override
    	public void onReceived(@NonNull CustomerInfo customerInfo) {
      		// access latest customerInfo
  		    if (customerInfo.getEntitlements().get(<your_entitlement_id>).isActive()) {
  						// user has access to "your_entitlement_id"
  				}
  	  }

      @Override
      public void onError(@NonNull PurchasesError error) {

      }
  });
  ```

  ```dart Flutter theme={null}
  try {
    CustomerInfo customerInfo = await Purchases.getCustomerInfo();
    // access latest customerInfo
    if (customerInfo.entitlements.all[<my_entitlement_identifier>].isActive) {
      // Grant user "pro" access
    }
  } on PlatformException catch (e) {
    // Error fetching customer info
  }
  ```

  ```typescript React Native theme={null}
  try {
    const customerInfo = await Purchases.getCustomerInfo();
    // access latest customerInfo
    if(typeof customerInfo.entitlements.active[<my_entitlement_identifier>] !== "undefined") {
  	  // Grant user "pro" access
  	}
  } catch (e) {
   // Error fetching customer info
  }
  ```

  ```csharp Unity theme={null}
  var purchases = GetComponent<Purchases>();
  purchases.GetCustomerInfo((customerInfo, error) =>
  {
    // access latest customerInfo
    if (customerInfo.Entitlements.Active.ContainsKey(<my_entitlement_identifier>)) {
    	// Unlock that great "pro" content
  	}
  });
  ```

  ```typescript Cordova theme={null}
  Purchases.getCustomerInfo(
    customerInfo => {
      // access latest customerInfo
      if(typeof customerInfo.entitlements.active[<my_entitlement_identifier>] !== "undefined") {
  			  // Grant user "pro" access
  		}
    },
    error => {
      // Error fetching customer info
    }
  );
  ```

  ```typescript Capacitor theme={null}
  await Purchases.addCustomerInfoUpdateListener((customerInfo) => {
    if(typeof customerInfo.entitlements.active[<my_entitlement_identifier>] !== "undefined") {
      // Grant user "pro" access
    }
  });
  ```
</CodeGroup>

Qonversion:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().checkEntitlements { (entitlements, error) in
    if let error = error {
      // handle error
      return
    }

    if let premium: Qonversion.Entitlement = entitlements["premium"], premium.isActive {
      // unlock feature
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] checkEntitlements:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull entitlements,
                                  NSError * _Nullable error) {
      QONEntitlement *premiumEntitlement = entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        // unlock feature
      }
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().checkEntitlements(new QonversionEntitlementsCallback() {
      @Override
      public void onSuccess(@NotNull Map<String, QEntitlement> entitlements) {
          final QEntitlement premiumEntitlement = entitlements.get("premium");

          if (premiumEntitlement != null && premiumEntitlement.isActive()) {
              // unlock feature
          }
      }

      @Override
      public void onError(@NotNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.checkEntitlements(object: QonversionEntitlementsCallback {
      override fun onSuccess(entitlements: Map<String, QEntitlement>) {
          val premiumEntitlement = entitlements["premium"]
          if (premiumEntitlement != null && premiumEntitlement.isActive) {
              // unlock feature
          }
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final Map<String, QEntitlement> entitlements = await Qonversion.getSharedInstance().checkEntitlements();
    final premium = entitlements['premium'];
    if (premium != null && premium.isActive) {
      // unlock feature
    }
  } catch (e) {
    print(e);
  }
  ```

  ```typescript React Native theme={null}
  try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
      // unlock feature
    }
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().CheckEntitlements((entitlements, error) =>
  {
      if (error == null)
      {
          if (entitlements.TryGetValue("premium", out Entitlement premium) && premium.IsActive)
          {
              // unlock feature
          }
      }
      else
      {
          // Handle the error
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
      const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

      const premiumEntitlement = entitlements.get('premium');
      if (premiumEntitlement != null) {
          // unlock feature
      }
  } catch (e) {
      // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const entitlements = await Qonversion.getSharedInstance().checkEntitlements();

    const premiumEntitlement = entitlements.get('premium');
    if (premiumEntitlement != null) {
      // unlock feature
    }
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

### Authorization system

<Info>
  ### Cross-device and cross-platform access

  Set up this section only if you need cross-device and cross-platform access and your project includes an authorization system.
</Info>

Qonversion lets you identify your signed-in users and unlock premium access across multiple devices. Use the `identify()` method to link a user to your signed-in subscriber. Call this method every time you want to use User Identity. For example, when a user logs in. User Identity provides a convenient way of managing premium access of your existing subscribers, including the following cases:

* A user reinstalls your app for any reason. Using the same User ID allows you to provide premium access linked to previously purchased products.
* A user logs in on several devices. You can provide premium access based on a subscription purchased on one of his devices.
* A user logs in on iOS and Android versions of your app. You can provide premium access based on a subscription purchased on one of the platforms.

#### Logging in

When a user logs into his account, call `identify()`.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.shared().identify("your_custom_user_id") { user, error in
    // use user if necessary
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] identify:@"your_custom_user_id"];

  // or the following option, if you want to get notified about the result.

  [[Qonversion sharedInstance] identify:@"your_custom_user_id" completion:^(QONUser * _Nullable user, NSError * _Nullable error) {
    // use user if necessary
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().identify("your_custom_user_id");

  // or the following option, if you want to get notified about the result.

  Qonversion.getSharedInstance().identify("your_custom_user_id", new QonversionUserCallback() {
      @Override
      public void onSuccess(@NonNull QUser user) {
          // use user if necessary
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.shared.identify("your_custom_user_id", object : QonversionUserCallback {
      override fun onSuccess(user: QUser) {
          // use user if necessary
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final userInfo = await Qonversion.getSharedInstance().identify("your_custom_user_id");
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript React Native theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.GetSharedInstance().Identify("your_custom_user_id", (userInfo, error) =>
  {
      if (error == null)
      {
          // use userInfo if necessary
      }
      else
      {
          // Handle the error
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```bash curl theme={null}
  curl --location --request POST 'https://api.qonversion.io/v3/identities/new_identities_user' \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "user_id": "QON_38a2d811afd54a433587620f8696266e"
  }'

  {
      "id": "new_identities_user",
      "user_id": "QON_38a2d811afd54a433587620f8696266e"
  }
  ```
</CodeGroup>

<Warning>
  ### Use the unique user ID stored in your database

  Always use unique user ID values. Otherwise, a user can get matched to another user's entitlements status.
</Warning>

To check entitlements for identified users, you can call the `checkEntitlements` function, which we discussed above.

#### Logging out

You need to call the `logout()` method to handle entitlements for an unauthorized user. Call this method when a user logs out within your app:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().logout()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] logout];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.logout()
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Logout();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().logout();
  ```
</CodeGroup>

When a user logs back into his account, don't forget to use `identify()` method again.

## User-base migration

Those steps have to be done to keep the system working smoothly for your current user base. The necessity of steps depends on the complexity of your system. The simplest system is represented by a single platform infrastructure (Apple, Google, or Stripe). The complex one includes a few platforms with authorization system, your backend infrastructure, and WebHooks handler.

### Client-side migration

Follow these steps to sync user status and retrieve the latest data from Google and Apple on your current device. Call the `syncHistoricalData()` method right after Qonversion SDK initialization to synchronize all the device-related data and ensure that none of the entitlements has been missed.

<Warning>
  ### Qonversion Android SDK 9.+ limitation

  For Qonversion Android SDK 9.+, the method `syncHistoricalData()` has been removed because of a limitation in Google Play Billing Library 8, which prevents the retrieval of historical purchases
</Warning>

### User-database migration

Once you have the app version with Qonversion SDK up and running, it's time to proceed to the server-side migration.

1. Prepare files with [AppStore with Base64 encoded receipt data](migrating-subscriptions#app-store-data-migration-file) or [Google Play with purchase tokens](migrating-subscriptions#google-play-data-migration-file). If you do not have receipt data or purchase tokens on your side but are already running your subscription management with a third-party vendor, you should ask the vendor's support team for the required data file.
2. Then simply **share the files with us** using our support chat and provide CSV files.

## Release

Once you're done with these steps go ahead and release your app. For complex systems with cross-platform access and authorization setups, make sure you're in touch with us and our team has verified your user database migration.

<Check>
  ### You're good to go

  Check out the detailed RevenueCat and Qonversion [feature comparison](https://qonversion.io/revenuecat-alternative) and don't hesitate to contact us if you have questions.
</Check>

***

[Migrating In-App Subscriptions](migrating-subscriptions)

[Migrating from Adapty to Qonversion](adapty-migration-guide)


# Migrating In-App Subscriptions
Source: https://documentation.qonversion.io/docs/migrating-subscriptions

How to integrate Qonversion with existing subscriber base

When you integrate Qonversion into your app with an existing subscriber base, it is important to migrate your subscribed users access management and import your historical transactions to get accurate historical analytics data.

Below you can find a simple step-by-step guide on how to migrate to Qonversion for both [Analytics and Subscription management modes](quickstart).

Additionally, you can [book a demo call](https://meetings.hubspot.com/qonversion/demo-request?utm_source=documentation\&utm_medium=link\&utm_campaign=migration) where we can discuss all the related details.

## Migration process overview

There are two mutually reinforcing types of data migration: client-side and server-side. Since both have pros and cons, we recommend following both of them to get accurate data in your Qonversion dashboard.

### Client-side vs Server-side migration

Client-side and Server-side are mutually reinforcing migration types, and here you can find why:

|                                                                  | Client-side migration                                                                                                     | Server-side migration                                                                                                                                        |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Historical revenue data depth                                    | Transactions for Google Play are restored with limited accuracy.                                                          | Restores all the transactions.                                                                                                                               |
| Historical revenue data quality                                  | Analytics properties like country, device OS, app version, and others are added automatically.                            | Analytics properties like country, device OS, app version, and others need to be provided from your side.                                                    |
| New revenue data                                                 | Tracks only users who installed the app with Qonversion SDK integrated.                                                   | Tracks all the subscriptions active for the moment of data migration (but not new ones).                                                                     |
| Grant subscribers premium access for cross-platform applications | Qonversion grants users an entitlement after launching the app only on the platform where the subscription was purchased. | Qonversion provides entitlements independently of the platform right after the app launches.                                                                 |
| How to launch?                                                   | As easy as it sounds, add an additional line of code to your app                                                          | Needs resources allocation from your side: prepare a file with all the historical Base64 encoded receipt data for AppStore or purchase tokens for GooglePlay |

### Recommended migration approach

To leverage all the pros of both migration types, we recommend the following approach:

#### Client-side migration

Let's start with client-side migration:

1. **Integrate Qonversion SDK** to track analytics and entitlements for your new subscribers using our [quick start guide](quickstart).
2. Call the [*syncHistoricalData*](migrating-subscriptions#sdks-synchistoricaldata-method) method right after Qonversion SDK initialization to synchronize all the device-related data and ensure that none of the entitlements has been missed.
3. Launch your app update to production.
4. After the steps above, you will process new purchases with Qonversion, while your subscribers with the previous app version will continue tracking throughout your system.

#### Server-side migration

Once you have the app version with Qonversion SDK up and running, it's time to proceed to the server-side migration.

1. Prepare files with [AppStore with Base64 encoded receipt data](migrating-subscriptions#app-store-data-migration-file) or [Google Play with purchase tokens](migrating-subscriptions#google-play-data-migration-file).

   1. If you do not have receipt data or purchase tokens on your side but are already running your subscription management with a third-party vendor, you should ask the vendor’s support team for the required data file.
   2. Additionally, but not necessarily, to keep your historical data granular, provide us with such user attributes as [Country, IDFV, IDFA, GAID, AAID, etc.](migrating-subscriptions#additional-user-related-fields-for-analytics).

2. Then simply **share the files with us** using our [support chat](https://dash.qonversion.io/account/profile?intercom=open) or [book a demo call](https://meetings.hubspot.com/qonversion/demo-request?utm_source=documentation\&utm_medium=link\&utm_campaign=migration) to discuss all the related details. Additionally, you can also contact us using [email](/docs/cdn-cgi/l/email-protection#59313c3529192836372f3c2b2a303637773036662a2c3b333c3a2d641d382d387914303e2b382d303637) and provide CSV files for iOS or Android.

<Check>
  ### Congratulations! After accomplishing the steps above, you will have accurate data and relevant entitlements for all of your users in Qonversion.
</Check>

## Migration details

Every migration step has its own vital details:

### Entitlements (Premium access) migration

Ensure you [have configured Entitlements and Products](subscription-management-mode#1-configure-products--entitlements-permissions) before you start users' entitlements migration process, so Qonversion can determine what entitlements should be granted to a user based on product ID of the purchased product.

### SDK's syncHistoricalData() method

Calling the *syncHistoricalData* method on each app launch is safe. We have extra checks for such cases, so no additional logic is required.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().syncHistoricalData()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] syncHistoricalData];
  ```

  ```java Java theme={null}
  // Deprecated starting Android SDK 9.+
  Qonversion.getSharedInstance().syncHistoricalData();
  ```

  ```kotlin Kotlin theme={null}
  // Deprecated starting Android SDK 9.+
  Qonversion.shared.syncHistoricalData()
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().syncHistoricalData();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().syncHistoricalData();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SyncHistoricalData();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().syncHistoricalData();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().syncHistoricalData();
  ```
</CodeGroup>

<Warning>
  ### Qonversion Android SDK 9.+ limitation

  For Qonversion Android SDK 9.+, the method `syncHistoricalData()` has been deprecated because of a limitation in Google Play Billing Library 8, which prevents the retrieval of historical purchases
</Warning>

### App Store data migration file

There are several required fields in the file for App Store transactions import:

| Field         | Required | Description                                                                                                                                                                                |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_id`     | yes      | Your-side user identifier                                                                                                                                                                  |
| `receipt`     | yes      | The Base64 encoded receipt data.                                                                                                                                                           |
| `product_id`  | yes      | The unique identifier of the product purchased.                                                                                                                                            |
| `original_id` | yes      | The transaction identifier of the original purchase. See the details here: [original\_transaction\_id](https://developer.apple.com/documentation/appstorereceipts/original_transaction_id) |
| `price`       | yes      | The initial purchase price in the original currency at the time of transaction.                                                                                                            |
| `currency`    | yes      |                                                                                                                                                                                            |

### Google Play data migration file

There are several required fields in the file for Google Play transactions import:

| Field            | Required | Description                                                                                                                                                            |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`        | yes      | Your-side user identifier                                                                                                                                              |
| `purchase_token` | yes      | The Base64 encoded purchase token.                                                                                                                                     |
| `product_id`     | yes      | The unique identifier of the product purchased.                                                                                                                        |
| `original_id`    | yes      | The original transaction ID, see the details here: [orderId](https://developer.android.com/reference/com/android/billingclient/api/Purchase#getOrderId\(\)) for Google |

### Stripe data migration file

There are several required fields in the file for Stripe transactions import:

| Field             | Required | Description                                                                                                                                                          |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`         | yes      | Your-side user identifier                                                                                                                                            |
| `product_id`      | yes      | Stripe unique identifier of the product purchased                                                                                                                    |
| `subscription_id` | yes      | Stripe unique identifier for the subscription purchased                                                                                                              |
| `currency`        | yes      | Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies) |
| `price`           | yes      | A positive float with two decimal points (or zero for a free price) indicates the amount to charge                                                                   |
| `purchase_date`   | no       | Unix timestamp of the purchase date                                                                                                                                  |

### Additional user-related fields for analytics

For more granular analytics, we also encourage you to provide us with the following data:

| Field        | Required | Description  |
| ------------ | -------- | ------------ |
| `idfv`       | no       | iOS Only     |
| `idfa`       | no       | iOS Only     |
| `gaid`       | no       | Android Only |
| `aaid`       | no       | Android Only |
| `country`    | no       |              |
| `model`      | no       |              |
| `os_version` | no       |              |

***

[Google Developer Notifications](google-developer-notifications)

[Migrating from RevenueCat](migrating-from-revenuecat-to-qonversion)


# Mixpanel
Source: https://documentation.qonversion.io/docs/mixpanel

Send in-app iOS and Android subscription and purchase events to Mixpanel

Qonversion sends valuable in-app revenue events, including purchases, subscriptions after free trials, subscription renewals, and even refunds to your Mixpanel account. This allows you to match your user behavior with their payment data in Mixpanel, and inform your product decisions. Qonversion validates user receipts directly with App Stores, so the revenue events are tracked even if a user does not open the app.

## 1. Set up the SDKs

1. Make sure you have Mixpanel SDK installed. If you do not have Mixpanel integration yet, please use [this documentation](https://developer.mixpanel.com/docs/implement-mixpanel#mixpanel-sdks).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Attribute events sent from Qonversion and events received from the Mixpanel SDK to the same user by setting the same user id to Mixpanel that you set to Qonversion SDK in the [User Identifiers guide](user-identifiers#2-user-id-for-third-party-integrations).

<CodeGroup>
  ```swift Swift theme={null}
  Mixpanel.mainInstance().identify(distinctId: "yourSideUserID")
  ```

  ```objectivec Objective-C theme={null}
  [[Mixpanel sharedInstance] identify:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  MixpanelAPI mixpanel =
      MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

  mixpanel.identify("yourSideUserID");
  ```

  ```dart Flutter theme={null}
  mixpanel.identify("yourSideUserID");
  ```

  ```typescript React Native theme={null}
  Mixpanel.identify('yourSideUserID');
  ```

  ```csharp Unity theme={null}
  Mixpanel.Identify('yourSideUserID');
  ```
</CodeGroup>

**→[Read more about user identifiers here](user-identifiers)**

<Warning>
  ### Do not track any purchase events on the client side

  Qonversion tracks all revenue events, so if you track revenue events with Mixpanel SDK, you may double-count the revenue in your Mixpanel account.
</Warning>

## 2. Configure the Mixpanel Integration

1. Go to your Mixpanel [Project Settings](https://mixpanel.com/login/?next=/settings/account#projects) and copy your token:

<img alt="" />

2. Navigate to the Integrations section in your Qonversion project, select [Mixpanel ](https://dash.qonversion.io/app/integration/mixpanel), and provide the **Token** and Save.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Mixpanel account.
</Check>

## Event Payload

In case you need details about data sent to Mixpanel, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "event":"subscription_started",
     "properties":{
        "distinct_id":"user_id",
        "Product Name":"product_id",
        "time":1616128486,
        "token":"",
        "$insert_id":"",
        "Product Price":9.9,
        "$append":{
           "$transactions":{
              "$amount":9.9,
              "$time":"2021-03-19T04:34:46",
              "product_id":"product_id"
           }
        }
     }
  }
  ```
</CodeGroup>

***

[Mailchimp](mailchimp)

[OneSignal](onesignal)


# Monitoring
Source: https://documentation.qonversion.io/docs/monitoring

Real-time analytics for your mobile app with in-app subscriptions

The Qonversion Monitoring page is a customizable dashboard allowing you to track your app's critical metrics. You can choose which metrics to display, such as Sales, MRR, Active Subscriptions, New-User-to-Paid Conversion rate, and more, and arrange them in the order that makes the most sense for your needs. This lets you focus on the metrics that matter most to you and your team.

Plus, the dashboard is saved per user, so you can customize it to your preferences and needs rather than having a one-size-fits-all approach for your entire organization. This makes it easy to stay on top of your app's performance and make data-driven decisions tailored to your needs.

## Available metrics

You can add a widget with any metric that is present in the Qonversion Dashboard:

1. [New Users Overview](users#new-users-overview)
2. [New-User-to-Trial Conversion](users#new-user-to-trial-conversion)
3. [New-User-to-Paid Conversion](users#new-user-to-paid-conversion)
4. [Active Trials](trials#active-trials)
5. [New Trials](trials#new-trials)
6. [Trials Movement](trials#trials-movement)
7. [Trial-to-Paid Conversion](trials#trial-to-paid-conversion)
8. [Trials Cancellation Rate](trials#trials-cancellation-rate)
9. [Active Subscriptions](subscriptions#active-subscriptions)
10. [New Subscriptions](subscriptions#new-subscriptions)
11. [Subscriptions Movement](subscriptions#subscriptions-movement)
12. [Subscriptions Cancellation Rate](subscriptions#subscriptions-cancellation-rate)
13. [Sales](revenue#sales)
14. [Proceeds](revenue#proceeds)
15. [Refunds](revenue#refunds)
16. [Refund Rate](revenue#refund-rate)
17. [MRR](revenue#mrr)
18. [MRR Movement](revenue#mrr-movement)
19. [ARR](revenue#arr)
20. [ARR Movement](revenue#arr-movement)
21. [Events](events-analytics)

## How to set up

Qonversion Monitoring dashboard can be flexibly customized. We'll provide a step-by-step guide for:

* Adding widgets
* Configuring them to display the metrics that matter most to you
* Arranging the widgets in the order that makes the most sense for your needs.

<Frame>
  <img />
</Frame>

### Adding widgets

To add a new widget to your dashboard:

1. Click the **Add a widget** button in the top-right toolbar.
2. Choose one of the available metrics from the drop-down menu, grouped by category (Revenue, New users, Trials, Subscriptions, Events, and Others).

<Frame>
  <img />
</Frame>

### Configuring widgets

To configure a widget according to your needs:

1. Hover the widget's top-right corner and click the settings button.

2. Adjust any of the following attributes:

   1. Metric to Display (one of the 21 available metrics)
   2. Data format (cumulative or incremental)
   3. Grouping option
   4. Store filter
   5. Period to display (from Current Day to Last Year)
   6. Widget's Title
   7. Chart Type
   8. Chart Width

3. Click the Save button.

### Arranging widgets

To arrange widgets in the order that makes the most sense for your needs:

1. Hover the widget's top-right corner and press the drag-n-drop button.
2. Place the widget in the desired place on the dashboard
3. Release the drag-n-drop button

## Cumulative Data Format

In the widget's settings, you can find an option to choose cumulative data format.

Once you have activated the cumulative data format, each data point starts representing the total for that metric up to that point in time rather than just the value for that specific period.

Additionally, after choosing the **Line** chart type, the widget displays data of the same length from the previous period. Please note that this feature works only for the following period to display: Current Day, Current Week, Current Month, and Current Year.

## Percentages explained

One of the features of the dashboard charts is the percentage-based comparison with the previous period of the same length. The value is calculated by following steps:

1. We take the chart's value (a number which is located to the left of the percentage)

2. Compare the value with the one calculated accordingly to the widget's period to display setting:

   1. Current day -> The same day the previous week until the current time
   2. Current week -> Previous week until the current time
   3. Current month -> Previous month until the current time
   4. Current year -> Previous year until the current time
   5. Last day -> 24 hours before "last day"
   6. Last week - > A week before "last week"
   7. Last month -> A month before "last month"
   8. Last year -> A year before "last year"

## Additional Features

### TV Mode

TV Mode allows you to view the monitoring dashboard in full-screen mode. Toggle it with the TV icon in the top-right toolbar.

<Frame>
  <img />
</Frame>

### Real-time updates

You can enable real-time updates in the monitoring dashboard to analyze your metrics in real-time. Toggle the play icon in the top-right toolbar; the data is then updated every minute.

<Frame>
  <img />
</Frame>

***

[Analytics](analytics)

[Revenue](revenue)


# Lottie Component Source
Source: https://documentation.qonversion.io/docs/no-code-component-lottie-src

How to obtain a link for a Lottie animation to use within the Qonversion No-Code Builder.

This guide explains how to obtain a link for a Lottie animation to use within the Qonversion No-Code Builder.

## Steps to Get a Lottie Animation Link

### 1. Sign up and log in to LottieFiles

Begin by creating an account on the [LottieFiles](https://lottiefiles.com) platform and logging in with your credentials.

### 2. Create or select animation

You have two options:

* Choose from the extensive library available on the site
* Create your own custom animation

### 3. Open the Handoff section

Click on the **Handoff** button on the top right side. It will open the Download & Handoff section with the Handoff tab selected.

### 4. Copy the asset link URL

Copy the asset link URL and paste it into your Qonversion No-Code Builder component configuration.


# Overview
Source: https://documentation.qonversion.io/docs/no-codes

Build, test, and update in-app screens — instantly.

**Qonversion No-Code Builder 2.0** lets you create, customize, and update paywalls, onboarding flows, and promotional screens without releasing a new app version.

Design visually, connect real products, and publish updates directly from your Qonversion dashboard — no code or developer input required.

**Use the Builder to power:**

* Paywalls – for subscriptions or one-time offers
* Onboarding flows – single- or multi-page user journeys
* Promotional screens – for seasonal offers, upsells, or experiments

No rebuilds. No release cycles. Just publish and go live in seconds.

<img alt="Qonversion No-Code Builder" />

***

## Getting Started

Access the Builder from the left sidebar of your Qonversion dashboard.

When creating a new screen, first choose what type of screen you’re building:

* **Mobile Paywall** — a single-page layout for offers or subscriptions.
* **Mobile Onboarding** — a multi-page screen for onboarding or other flows.

After selecting the screen type, you can decide how to start:

* **Start from a Template** – pick a ready-made layout from the gallery.
* **Design from Scratch** – create your own layout using flexible components.

You can access the No-Code Builder from the left sidebar in your Qonversion dashboard. Simply navigate to the No-Code Screens section and follow this guide to start building or [follow this link](https://dash.qonversion.io/no-codes)

[A quick guide on creating screens with No-Code Builder](getting-started)

To use the **No-Codes**, you need to follow a few simple steps:

1. [Install the SDK](installation)
2. [Create No-Codes screen](getting-started)
3. [Display the screen](displaying-no-codes)

<img alt="" />

***

## Templates

Templates in Qonversion help you build screens faster by starting from ready-made layouts designed for paywalls, onboarding, and other in-app experiences. You can choose from single-page or multi-page templates, preview them, and customize every element directly in the Builder.

* Save time by starting from pre-designed, tested layouts.
* Get inspiration from real-world paywall and onboarding patterns.
* Maintain design consistency across different screens.

<img alt="" />

***

### Template Types

* **Single-Page Templates** — ideal for paywalls, feature highlights, or promotional screens.
* **Multi-Page Templates** — designed for onboarding or connected screen flows, such as tutorials or multi-step funnels.

***

### Multi-Page Templates

Multi-page templates contain several connected screens within one flow. Each multi-page template in the gallery shows a page count indicator and a preview button. Hover over a template to open a modal preview and browse through all included pages before adding it to your project.

When you create a new screen and select **Mobile Onboarding**, the gallery automatically filters to show only **multi-page templates** — helping you find relevant layouts faster.

***

### How to Use Templates

1. Open the **Builder** → **Template Gallery** or tap **Create Screen** and choose a screen type (e.g., **Mobile Paywall** or **Mobile Onboarding**).
2. Browse available templates and use the **Preview** button to view details.
3. Click **Use Template** to add it to your project and start customizing.

***

[Custom Proxy Server](custom-proxy-server-for-sdks)

[Installation](installation)


# Screen Analytics
Source: https://documentation.qonversion.io/docs/no-codes-analytics

Track how your no-code screens perform — impressions, conversions, revenue, and more.

Qonversion Screen Analytics gives you a complete view of how your no-code screens perform. See which screens drive the most revenue, where users convert or drop off, and how different audiences engage with your paywalls and onboarding flows.

Tracking is fully automatic — once you update your SDK, data starts flowing with no additional setup.

<Info>
  Screen Analytics requires the following minimum SDK versions:

  | Platform | Minimum Version |
  | -------- | --------------- |
  | iOS      | 6.7.0           |
  | Android  | No-Codes 1.6.0  |

  If you're using an older SDK version, update to start collecting screen analytics data.
</Info>

***

## Overview

The Overview tab provides a high-level snapshot of how all your no-code screens perform together.

### KPI Cards

Six metric cards are displayed at the top, each showing the current value and a comparison to the previous period:

| Metric          | Description                                           |
| --------------- | ----------------------------------------------------- |
| **Impressions** | Total number of times screens were loaded             |
| **Views**       | Number of user interactions with screens              |
| **Purchases**   | Completed purchase events from screens                |
| **Trials**      | Trial subscription starts from screens                |
| **Revenue**     | Total revenue generated from screens (USD)            |
| **Conversion**  | Percentage of impressions that resulted in a purchase |

### Performance Chart

Below the KPI cards, an interactive chart lets you visualize any metric over time:

* **Metric switcher** — toggle between Impressions, Views, Purchases, Trials, Revenue, and Conversion
* **Chart types** — Line, Area, or Vertical Bar
* **Time unit** — Day, Week, or Month

### Top Screens

A leaderboard table shows your top 5 screens ranked by revenue. Each row displays the screen name along with all six metrics. Click any row to open its detail page.

<Frame>
  <img />
</Frame>

***

## Screens

The Screens tab shows a full table of all your no-code screens with their performance data.

* **Columns**: Screen, Impressions, Views, Purchases, Trials, Revenue, Conversion
* **Sort**: Click any column header to sort - cycle is ascending → descending → unsorted. The Top Screens widget on Overview is always ranked by Revenue (descending)
* **Search**: Find screens by name
* **Pagination**: Browse through all screens, 10 per page

Click any row to open the screen's detail page.

<Frame>
  <img />
</Frame>

***

## Screen Detail

Click on any screen to see its detailed analytics. The detail page provides deep insights into a single screen's performance.

### KPI Cards

Six metric cards with delta comparison to the previous period:

| Metric           | Description                                      |
| ---------------- | ------------------------------------------------ |
| **Revenue**      | Total revenue generated by this screen (USD)     |
| **Purchases**    | Completed purchase events                        |
| **Trials**       | Trial starts from this screen                    |
| **Refunds**      | Reversed purchases                               |
| **Conversion %** | Percentage of impressions that led to a purchase |
| **Cancel %**     | Percentage of purchases that were refunded       |

### Performance Chart

A time-series chart for this specific screen. Supports the same controls as the Overview chart — metric toggle, chart types, and time unit selector.

<Frame>
  <img />
</Frame>

***

### Conversion Funnel

See how users progress through your screen step by step.

* A bar chart shows the count at each step
* A table displays each step with the count and conversion percentage from the previous step

This helps you identify where users drop off and which steps need improvement.

<Frame>
  <img />
</Frame>

***

### Product Breakdown

Understand which products generate the most revenue from this screen.

* A bar chart compares revenue across products
* A table shows Product ID, Revenue, Purchases, Trials, and Refunds for each product

<Frame>
  <img />
</Frame>

***

### Audience Breakdown

Segment your screen's performance by audience dimensions:

* **Country** — where your users are located
* **Locale** — device language
* **Device** — device model
* **OS** — operating system version
* **Platform** — iOS or Android

Each dimension shows a table with Views, Purchases, and Revenue per segment.

<Frame>
  <img />
</Frame>

***

### User Behavior

Understand how users engage with your screen:

* **Avg. Time on Screen** — average session duration in seconds
* **Bounce Rate** — percentage of users who left without taking action
* **Time Spent Distribution** — a histogram showing how long users spend on the screen, grouped into time buckets
* **Page Flow** (multi-page screens only) — shows how users progress through pages, including progression percentage and exit rate per page

<Frame>
  <img />
</Frame>

***

## Controls

All analytics views share a common set of controls:

* **Date range** — select a custom range or use presets (7d, 30d, 60d, 90d)
* **Time unit** — choose between Day, Week, or Month granularity
* **Chart type** — switch between Line, Area, and Vertical Bar charts
* **Metric switcher** — toggle which metric is displayed on charts

### Filters

<Info>
  Analytics filters are coming soon. You will be able to narrow down data by specific attributes such as country, product, and more.
</Info>

***

[Success and Failure Actions](success-failure-actions)

[Using No-Codes with custom purchases handling](using-no-codes-with-custom-purchases-handling)


# Non-Subscription Purchases
Source: https://documentation.qonversion.io/docs/non-subscription-purchases

Use Qonversion to handle non-consumable and consumable in-app purchases

Qonversion allows handling all types of in-app purchases, including non-subscription products.

## Non-subscription In-app Purchase Types

**Consumable in-app purchases** These in-app purchases can be used just once. They are depleted and can be purchased again. They are usually linked to coins or gems that users purchase to spend on virtual resources in an app.

**Non-consumable in-app purchases** Non-consumable purchases are not depleted, as the name implies. You can unlock premium features in your app, like photo filters, fonts, or lifetime premium access.

## Entitlements and Products

An **Entitlement** unlocks access to the premium features of your application when a user makes a purchase. You can read more about Qonversion entitlements [here](entitlements). A **Product** in Qonversion is linked to a specific Apple and Google store product. You can read more about Qonversion products [here](create-products). To change the set of products offered to a user remotely without releasing app updates, use a [Remote Config](migrate-offerings-to-remote-configs).

## Providing lifetime access with in-app purchase

Use non-consumable in-app purchase to provide lifetime access and follow these steps:

1. Create an app store product:

* iOS: Create non-consumable in-app purchase on the [App Store Connect](https://appstoreconnect.apple.com/login).
* Android: Create an in-app product on [Google Play Developer Console](https://play.google.com/apps/publish/).

Let's assume the product has the following app store id `com.testgame.lifetime.99`.

<Note>
  On Google Play, one-time products can define multiple [purchase options](https://developer.android.com/google/play/billing/one-time-products). If you want a Qonversion product to map to a specific purchase option, set its identifier in the **Google Play Purchase Option ID** field when creating the product — the same way base plans work for subscriptions. Leave the field empty to use the product's default purchase option.
</Note>

2. Create Qonversion Product with qonversion ID `lifetime` and link it to the app store product from the previous step.

3. Create an Entitlement `premium` and link it to the Qonversion Product. This Entitlement will be active after a user purchases the product linked to it.

4. Optional: Create a [Remote Config](migrate-offerings-to-remote-configs) holding the product ID `lifetime`. Then you can easily change the list of products shown in your app without a release.

Use our guides on [making purchases](making-purchases#1-make-a-purchase) and [checking user entitlements](making-purchases#5-check-user-entitlements).

***

[Deferred Purchases](deferred-purchases)

[Store Product Price Changes](store-product-price-changes)


# [Nov 2025] Migration guide. iOS 6.0.0
Source: https://documentation.qonversion.io/docs/nov-2025-migration-guide-ios-600

In this major release of our Qonversion iOS SDK, we've incorporated numerous essential updates.

## No-Codes SDK merge into Qonversion SDK

We are now concluding the public beta phase of our No-Code Builder. Therefore, we have chosen to integrate No-Codes SDK with the Qonversion SDK. You no longer need to include separate packages to utilize Qonversion No-Codes.

If you installed No-Codes SDK through CocoaPods, simply substitute the No-Codes dependency with the Qonversion dependency. If you were using both, just remove the No-Codes package. Make sure to update your pods to access the latest version of the Qonversion SDK.

<CodeGroup>
  ```text podfile theme={null}
  // Before
  pod 'NoCodes'

  // Now
  pod 'Qonversion'
  ```
</CodeGroup>

If you have installed the No-Codes SDK using Swift Package Manager, please uninstall that package and import the package `https://github.com/qonversion/qonversion-ios-sdk` if you haven't done so already.

Integrating No-Codes into the Qonversion SDK requires renaming the public entities and interfaces since the `NoCodes` namespace is no longer available.

| Before                                | Now                                  |
| ------------------------------------- | ------------------------------------ |
| `NoCodes.Configuration`               | `NoCodesConfiguration`               |
| `NoCodes.Action`                      | `NoCodesAction`                      |
| `NoCodes.ActionType`                  | `NoCodesActionType`                  |
| `NoCodes.PresentationConfiguration`   | `NoCodesPresentationConfiguration`   |
| `NoCodes.PresentationStyle`           | `NoCodesPresentationStyle`           |
| `NoCodes.Delegate`                    | `NoCodesDelegate`                    |
| `NoCodes.ScreenCustomizationDelegate` | `NoCodesScreenCustomizationDelegate` |

## No-Code screens preloading

We are introducing a way to enhance the loading speed of your No-Code screens. With the new preloading feature, our SDK will fetch your screens immediately after initialization, ensuring that when you request them, there is no delay from API requests. The best part is that no coding is required; simply mark your screen as preloadable in the Qonversion dashboard, and you’re good to go. For more details, check out the related [documentation](screens-preloading).

## Automations removal

With this release, we are discontinuing the deprecated Automations support from the SDK. If you are still utilizing Automations, we encourage you to transition to our No-Code Builder. It offers a more flexible and supported approach to displaying your paywalls or onboarding flows without the need for custom development of these screens.

Your Automation screens will keep functioning with the earlier SDK versions until the complete support phase-out.

## Error Codes alignment

We are aligning our error codes with this release to make them clearer and simpler. Previously, there were two classes: `Qonversion.Error` and `Qonversion.APIError` (`QONError` and `QONAPIError` for Objective C). Now we merge them into a single class `Qonversion.ErrorCode` (`QONErrorCode` for Objective C) and changing some names as follows.

| Before                                        | Now                                               |
| --------------------------------------------- | ------------------------------------------------- |
| `QONErrorUnknown`                             | `QONErrorCodeUnknown`                             |
| `QONErrorCancelled`                           | `QONErrorCodePurchaseCanceled`                    |
| `QONErrorProductNotFound`                     | `QONErrorCodeProductNotFound`                     |
| `QONErrorClientInvalid`                       | `QONErrorCodeClientInvalid`                       |
| `QONErrorPaymentInvalid`                      | `QONErrorCodePaymentInvalid`                      |
| `QONErrorPaymentNotAllowed`                   | `QONErrorCodePaymentNotAllowed`                   |
| `QONErrorStoreFailed`                         | *removed*                                         |
| `QONErrorStoreProductNotAvailable`            | `QONErrorCodeStoreProductNotAvailable`            |
| `QONErrorCloudServicePermissionDenied`        | `QONErrorCodeCloudServicePermissionDenied`        |
| `QONErrorCloudServiceNetworkConnectionFailed` | `QONErrorCodeCloudServiceNetworkConnectionFailed` |
| `QONErrorCloudServiceRevoked`                 | `QONErrorCodeCloudServiceRevoked`                 |
| `QONErrorPrivacyAcknowledgementRequired`      | `QONErrorCodePrivacyAcknowledgementRequired`      |
| `QONErrorUnauthorizedRequestData`             | `QONErrorCodeUnauthorizedRequestData`             |
| `QONErrorIncorrectSharedSecret`               | *removed*                                         |
| `QONErrorConnectionFailed`                    | `QONErrorCodeNetworkConnectionFailed`             |
| `QONErrorInternetConnectionFailed`            | *removed*                                         |
| `QONErrorDataFailed`                          | *removed*                                         |
| `QONErrorInternalError`                       | `QONErrorCodeInternalError`                       |
| `QONErrorStorePaymentDeferred`                | `QONErrorCodePurchasePending`                     |
| `QONErrorRemoteConfigurationNotAvailable`     | `QONErrorCodeRemoteConfigurationNotAvailable`     |
| `QONErrorOfferingsNotAvailable`               | `QONErrorCodeOfferingsNotAvailable`               |
| `QONAPIErrorFailedReceiveData`                | `QONErrorCodeFailedToReceiveData`                 |
| `QONAPIErrorFailedParseResponse`              | `QONErrorCodeResponseParsingFailed`               |
| `QONAPIErrorIncorrectRequest`                 | `QONErrorCodeResponseParsingFailed`               |
| `QONAPIErrorInternalError`                    | `QONErrorCodeBackendError`                        |
| `QONAPIErrorUnknown`                          | `QONErrorCodeUnknown`                             |
| `QONAPIErrorInvalidCredentials`               | `QONErrorCodeInvalidCredentials`                  |
| `QONAPIErrorInvalidClientUID`                 | `QONErrorCodeInvalidClientUID`                    |
| `QONAPIErrorUnknownClientPlatform`            | `QONErrorCodeUnknownClientPlatform`               |
| `QONAPIErrorFraudPurchase`                    | `QONErrorCodeFraudPurchase`                       |
| `QONAPIErrorFeatureNotSupported`              | `QONErrorCodeFeatureNotSupported`                 |
| `QONAPIErrorAppleStoreError`                  | `QONErrorCodeAppleStoreError`                     |
| `QONAPIErrorPurchaseInvalid`                  | `QONErrorCodePurchaseInvalid`                     |
| `QONAPIErrorProjectConfigError`               | `QONErrorCodeProjectConfigError`                  |
| `QONAPIErrorInvalidStoreCredentials`          | `QONErrorCodeInvalidStoreCredentials`             |
| `QONAPIErrorReceiptValidation`                | `QONErrorCodeReceiptValidationError`              |
| `QONAPIErrorRateLimitExceeded`                | `QONErrorCodeApiRateLimitExceeded`                |

## Proxy URL for No-Codes

You can now set a proxy URL for all the No-Codes requests. To do it, just provide the proxy URL to the No-Codes configuration during the initialization as follows:

<CodeGroup>
  ```swift Swift theme={null}
  // Set proxy URL during initialization
  let configuration = NoCodesConfiguration(
      projectKey: "projectKey",
      proxyURL: "https://your-proxy-server.com"
  )
  NoCodes.initialize(with: configuration)

  // Or set proxy URL using configuration object
  var configuration = NoCodesConfiguration(projectKey: "projectKey")
  configuration.proxyURL = "https://your-proxy-server.com"
  NoCodes.initialize(with: configuration)
  ```
</CodeGroup>

## Other changes

The `IntroEligibilityStatus` `NonIntroProduct` was renamed to more correct `NonIntroOrTrialProduct` (`QONIntroEligibilityStatusNonIntroProduct` to `QONIntroEligibilityStatusNonIntroOrTrialProduct` for Objective C).

***

[\[Jan 2026\] Migration guide. Capacitor 1.](jan-2026-migration-guide-capacitor-1)

[\[Sep 2025\] Migration guide. React Native 10.](sep-2025-migration-guide-react-native-10)


# Offline SDK mode
Source: https://documentation.qonversion.io/docs/offline-sdk-mode

Qonversion SDKs work when there is no internet connection on the device, or Qonversion API is inaccessible for a short time. Please take a look at the details of this mode below.

## Products

The information about your Products is crucial to show a paywall and create a purchase. Qonversion SDKs have a built-in cache that preprocesses this data and makes it available to help you offer top-notch UX for your customers.

## Entitlements

Entitlements are the central part of subscription-based access management. Once your app user purchases using our SDK, the SDK returns the currently available subscription status or the cached status during a lack of internet connection or issues with Qonversion API. **The cached subscription state is available for one month by default.**

You can change the duration according to your needs while configuring Qonversion as follows:

<CodeGroup>
  ```swift Swift theme={null}
  let config = Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
  config.setEntitlementsCacheLifetime(.year)
  Qonversion.initWithConfig(config)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
  [configuration setEntitlementsCacheLifetime:QONEntitlementsCacheLifetimeYear];
  [Qonversion initWithConfig:configuration];
  ```

  ```java Java theme={null}
  final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
          this,
          "projectKey",
          QLaunchMode.SubscriptionManagement
  )
          .setEntitlementsCacheLifetime(QEntitlementsCacheLifetime.Year)
          .build();
  Qonversion.initialize(qonversionConfig);
  ```

  ```kotlin Kotlin theme={null}
  val qonversionConfig = QonversionConfig.Builder(
      this,
      "projectKey",
      QLaunchMode.SubscriptionManagement
  )
      .setEntitlementsCacheLifetime(QEntitlementsCacheLifetime.Year)
      .build()
  Qonversion.initialize(qonversionConfig)
  ```

  ```dart Flutter theme={null}
  final config = new QonversionConfigBuilder(
    	'projectKey',
    	QLaunchMode.subscriptionManagement
  )
    	.setEntitlementsCacheLifetime(QEntitlementsCacheLifetime.year)
    	.build();
  Qonversion.initialize(config);
  ```

  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEntitlementsCacheLifetime(EntitlementsCacheLifetime.YEAR)
    .build();
  Qonversion.initialize(config);
  ```

  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      )
          .SetEntitlementsCacheLifetime(EntitlementsCacheLifetime.Year)
          .Build();
  Qonversion.Initialize(config);
  ```

  ```typescript Cordova theme={null}
  const config = new Qonversion.ConfigBuilder(
    'projectKey',
    Qonversion.LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEntitlementsCacheLifetime(Qonversion.EntitlementsCacheLifetime.YEAR)
    .build();
  Qonversion.initialize(config);
  ```

  ```typescript Capacitor theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEntitlementsCacheLifetime(EntitlementsCacheLifetime.YEAR)
    .build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

Let's have a look at the following hypothetical example:

1. A user purchases a *weekly* subscription.
2. He sets off on a long journey without internet access. But he wants to continue using your premium features offline.
3. Qonversion SDK will be returning information that this particular user is eligible for premium access for one month if the user does not connect to the internet during this period.
4. Eventually, when he opens the app with an internet connection available, Qonversion will update subscription statuses and show the current state accordingly.

## Purchases

Purchases are the third critical part of subscription management. We guarantee data completeness in this case as well. If, for some reason, our SDK cannot complete the purchase through Qonversion API in real-time, the SDK stores the data on the device and resends it at the next app launch. Your users will have a seamless experience: even if we cannot get a response from our servers (network or API outages), we will locally determine entitlements (based on previously loaded information) and provide correct user access. Then, we will also update the eligibility with the first successful request to our API.

## SDK versions to use this feature

| SDK          | Version |
| ------------ | ------- |
| IOS          | 2.20.0+ |
| Android      | 3.3.0+  |
| Unity        | 3.5.0+  |
| Flutter      | 4.4.0+  |
| React Native | 3.4.0+  |
| Cordova      | 2.0.0+  |
| Capacitor    | 0.1.0+  |

***

[Subscription Status](check-permissions)

[User Identifiers](user-identifiers)


# OneSignal
Source: https://documentation.qonversion.io/docs/onesignal

Send in-app subscription events to OneSignal to win back your subscribers

Qonversion sends mobile subscription events to OneSignal to automate push notifications with special offers to users who cancel a trial or a subscription. A personalized push notification with a special offer to a user who just canceled his trial or subscription can significantly uplift your app's revenue.

## 1. Set up the SDKs

1. Make sure you have OneSignal SDK installed. If you do not have OneSignal integration yet, please use [this documentation](https://documentation.onesignal.com/docs#sdk-guides).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Additionally, to attribute events sent from Qonversion, you need to set the same user ID at `_q_custom_user_id` key using the `Qonversion.shared().setProperty` method. Follow the [documentation](user-properties) to learn more about this method.

4. Set the same user ID by using OneSignal SDK:

<CodeGroup>
  ```swift Swift theme={null}
  OneSignal.setExternalUserId("yourSideUserID")
  ```

  ```objectivec Objective-C theme={null}
  [OneSignal setExternalUserId:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  OneSignal.setExternalUserId("yourSideUserID");
  ```

  ```kotlin Kotlin theme={null}
  OneSignal.setExternalUserId("yourSideUserID")
  ```
</CodeGroup>

<Info>
  The `setExternalUserId` method is deprecated in version 5+ of Onesignal SDKs. Instead, the External User ID will now be called External ID and will be used as the default alias for the new `OneSignal.login method`

  See the [User Model Migration Guide](https://documentation.onesignal.com/docs/user-model-migration-guide) for more details.
</Info>

## 2. Configure the OneSignal Integration

1. Get your **OneSignal App ID** following [this documentation](https://documentation.onesignal.com/docs/accounts-and-keys).

2. Navigate to the Integrations section in your Qonversion project, select [OneSignal](https://dash.qonversion.io/app/integration/onesignal), and provide the **App ID** and Save.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your OneSignal account.
</Check>

## How to Test

To test the integration, create a custom segment using a user tag labeled `q_status` with the desired value. Qonversion sets up a custom tag for users based on their most recent subscription status.

<img alt="" />

## Event Payload

The event names correspond to the OneSignal Tag Values.

Qonversion uses the **q\_status** tag with the event names to add data attributes to your OneSignal users. For example:

<CodeGroup>
  ```json theme={null}
  {
     "tags":{
        "q_status":"trial_converted"
     }
  }
  ```
</CodeGroup>

***

[Mixpanel](mixpanel)

[Pushwoosh](pushwoosh)


# Paddle Credentials
Source: https://documentation.qonversion.io/docs/paddle-credentials

Where to get your Paddle API key and where to paste it in the Qonversion dashboard.

To connect Paddle, Qonversion needs a Paddle **API key**. Qonversion uses this key to register the webhook destination on your Paddle account automatically (you don't need to create the webhook yourself) and to read your products, transactions, subscriptions, refunds, and customers so it can grant entitlements and report revenue.

## Required permissions

Grant the API key the permissions below when you create it. Qonversion validates the key on connect and reports a missing **Notification settings: Write** scope explicitly, but the read scopes are required for ongoing processing — a key without them connects but then fails to sync data or map customers to users.

| Paddle entity         | Access       | Used for                                                                                                                                    |
| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Notification settings | Read & Write | Registering and verifying the webhook destination Qonversion creates for you                                                                |
| Products              | Read         | Validating the key on connect and matching your Paddle products                                                                             |
| Transactions          | Read         | Reading purchase / transaction details for analytics and entitlements                                                                       |
| Subscriptions         | Read         | Tracking renewals, plan changes, and cancellations                                                                                          |
| Adjustments           | Read         | Detecting refunds                                                                                                                           |
| Customers             | Read         | Resolving the buyer to a Qonversion user (the `custom_data` fallback — see [Send Paddle Purchases to Qonversion](initiate-purchase-paddle)) |

## 1. Get your Paddle API key

Paddle keeps **Production** and **Sandbox** in fully separate environments, each with its own API key. Generate the key in the environment you want to connect.

* **Production** — open [Paddle Developer Tools → Authentication](https://vendors.paddle.com/authentication-v2). Production keys start with `pdl_live_`.
* **Sandbox** — sign in to the [Paddle sandbox dashboard](https://sandbox-vendors.paddle.com) and open [Developer Tools → Authentication](https://sandbox-vendors.paddle.com/authentication-v2). Sandbox keys start with `pdl_sdbx_`. If you don't have a sandbox account yet, [sign up here](https://sandbox-login.paddle.com/signup).

Create a new API key (or copy an existing one) with the permissions listed in [Required permissions](#required-permissions) above, and copy its value.

<Warning>
  Treat the API key like a password. Paddle shows it in full only once when created — copy it immediately. After you connect it, Qonversion only ever displays a masked value, never the full key.
</Warning>

## 2. Paste the key into Qonversion

1. Open **Project Settings → Stores** in the [Qonversion dashboard](https://dash.qonversion.io/project-settings/stores) and find the **Paddle** card.
2. Click **Configure Paddle** to open the Paddle drawer. Production and Sandbox are managed side by side.
3. In the matching mode section, paste your API key into the **API Key** field and click **Connect Production** or **Connect Sandbox**.

Once connected, the section shows a **Connected** badge and the masked key. Qonversion registers the webhook destination on your Paddle account at this point — there is no separate webhook secret to paste.

## 3. Verify the connection

After connecting, use the buttons in the Paddle drawer to confirm everything works:

* **Test Connection** — checks that the saved API key is valid.
* **Test Webhook** (Sandbox) — confirms a webhook fired by Paddle reaches Qonversion.

A green result means the credentials are valid and Qonversion is receiving Paddle notifications. If a test fails, double-check that you copied the key for the correct environment and that it has all of the [required permissions](#required-permissions) — in particular **Notification settings: Write**.

<Warning>
  If connecting fails because a Paddle notification destination already exists for this webhook URL but wasn't created by Qonversion, delete (or rename) that destination in Paddle under **Developer Tools → Notifications**, then connect again.
</Warning>

<Warning>
  Make sure to connect your **Production** API key before going live. Sandbox credentials cannot process real charges.
</Warning>

***

[Paddle Integration](paddle-integration)

[Test Purchases — Paddle](test-purchase-paddle)


# Paddle Integration
Source: https://documentation.qonversion.io/docs/paddle-integration

Connect your Paddle account to Qonversion to manage cross-platform subscribers and provide unified analytics for web payments.

Qonversion supports Paddle web payments. This integration allows Qonversion to manage cross-platform subscribers' access and provide analytics for payments made via Paddle on your website.

<Info>
  In case you are selling digital goods, you can not promote web payment options in your mobile app as it goes against the app stores' policies.
</Info>

## 1. Connect your Paddle account to Qonversion

Find the **Paddle** card in the Stores tab of your project settings in the [Qonversion dashboard](https://dash.qonversion.io/project-settings/stores) and click **Configure Paddle**.

Qonversion manages **Production** and **Sandbox** side by side — you can connect either or both. For each mode, paste the Paddle **API key** and click **Connect Production** or **Connect Sandbox**. See [Paddle Credentials](paddle-credentials) for where to get the API key.

<Info>
  Qonversion registers the webhook destination on your Paddle account automatically — you don't need to wire it up in Paddle. The API key must carry the [required permissions](paddle-credentials#required-permissions) (Notification settings read+write, plus read access on products, transactions, subscriptions, adjustments, and customers).
</Info>

Once connected, Qonversion streams subscriptions, renewals, and refunds from Paddle into your project. You have complete control over your Paddle account and can disconnect whenever you want.

## 2. Create Paddle products

You can create products using the Paddle [dashboard](https://vendors.paddle.com/products-v2) (or the [sandbox dashboard](https://sandbox-vendors.paddle.com/products-v2) for testing).

A Paddle product can have multiple prices — more about setting up Paddle catalog products in [Paddle official documentation](https://developer.paddle.com/build/products/create-products-prices).

You can use the Paddle dashboard to create a subscription manually, but the most common way is to use [Paddle Checkout](https://developer.paddle.com/build/checkout/build-overlay-checkout) on your website to collect the customer's payment information. You can check the details of working with Paddle subscriptions using the API [here](https://developer.paddle.com/api-reference/overview).

## 3. Add your Paddle products to Qonversion

<Info>
  Skip this step if you are not using the [Qonversion Subscription Management mode](subscription-management-mode).
</Info>

Add your Paddle products to the [dashboard](https://dash.qonversion.io/entitlements/products) to manage cross-platform subscribers' access.

Make sure that the Paddle Product Identifier that you provide to Qonversion matches your Product ID in Paddle (it starts with `pro_`). You can find your Product ID in the Paddle Catalog on the product [page](https://vendors.paddle.com/products-v2).

## 4. Link Paddle purchases to a Qonversion user

Every Paddle purchase must be linked to a Qonversion user. The recommended way is to tag the Paddle Checkout with the buyer's Qonversion User ID in `custom_data` — Qonversion reads it from the Paddle webhook and grants entitlements and tracks revenue automatically, including for later renewals, refunds, and cancellations. No purchase-submission call is required.

<CodeGroup>
  ```javascript Paddle.js overlay checkout theme={null}
  Paddle.Checkout.open({
    items: [{ priceId: 'pri_01hv4rrk', quantity: 1 }],
    customData: {
      qonversion_client_uid: '<QONVERSION_USER_ID>',
    },
  });
  ```
</CodeGroup>

<Info>
  The key must be exactly `qonversion_client_uid`, and its value is the Qonversion User ID (the `qonversionId` from the SDK's `userInfo()`). If a transaction's `custom_data` is empty, Qonversion falls back to the Paddle customer's `custom_data`. See [Send Paddle Purchases to Qonversion](initiate-purchase-paddle) for the customer-level fallback and how to obtain the Qonversion User ID.
</Info>

Alternatively, you can submit the completed purchase yourself from your server via the [API endpoint](/reference/overview), or from the browser with the [Qonversion Web SDK](web-sdk). Capture the Paddle identifiers from the completed transaction — the `transaction_id` (`txn_`), the `product_id` (`pro_`), and, for subscriptions, the `subscription_id` (`sub_`). Note that the `subscription_id` is created asynchronously and is **not** in the client-side `checkout.completed` event — read it from the `transaction.completed` / `subscription.created` webhook (or `GET /transactions/{id}`) before submitting. See [Send Paddle Purchases to Qonversion](initiate-purchase-paddle) for the full reference. Then send them to Qonversion:

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.qonversion.io/v3/users/{user_id}/purchases \
    --header 'Authorization: Bearer {project_key}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "currency": "USD",
      "price": "11.99",
      "purchased": 1653458781,
      "paddle_store_data": {
        "type": "subscription",
        "transaction_id": "txn_01hv4rrk",
        "subscription_id": "sub_01hv4rrk",
        "product_id": "pro_01hv4rrk"
      }
    }'
  ```
</CodeGroup>

| Qonversion request field             | Source                                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------------------- |
| currency                             | transaction currency code                                                              |
| price                                | transaction total                                                                      |
| purchased                            | Unix-epoch seconds when the Paddle Checkout completed                                  |
| paddle\_store\_data.type             | `subscription` for recurring products, `non_recurring` for one-time purchases          |
| paddle\_store\_data.transaction\_id  | Paddle transaction id (`txn_`)                                                         |
| paddle\_store\_data.subscription\_id | Paddle subscription id (`sub_`). Required for `subscription`; omit for `non_recurring` |
| paddle\_store\_data.product\_id      | Paddle product id (`pro_`)                                                             |

See [Send Paddle Purchases to Qonversion](initiate-purchase-paddle) for the full request reference and the Web SDK alternative.

Qonversion updates data on Paddle subscriptions automatically. Usually, it happens with a slight delay compared to its actual state in Paddle.

## 5. Test your integration

Verify the connection end to end using the Paddle **sandbox** before going live. See [Test Purchases — Paddle](test-purchase-paddle).

## Limitations

**Proration**

Subscription changes such as upgrades or downgrades can result in prorated amounts. A prorated **charge** (typically on an upgrade) arrives as a transaction and **is** counted in revenue at its prorated amount. A prorated **credit** (typically on a downgrade) is issued by Paddle as an adjustment and is **not** reflected in Qonversion's revenue.

**Cancellations**

Paddle supports cancelling a subscription immediately or at the end of the current billing period (similar to in-app subscriptions on the app stores). Qonversion treats the cancellation as the terminal "expired" event and updates the subscriber's access accordingly.

**Coupons, discounts, and price changes**

Qonversion will take into account price changes, including discounts, applied to a subscription in revenue calculation.

**Refunds**

Qonversion tracks only full refunds. Proration or partial refunds are not supported currently.

***

[Stripe Integration](stripe-integration)

[Web SDK](web-sdk)


# Pause experiments
Source: https://documentation.qonversion.io/docs/pause-experiments

Pause your experiment to analyse exposed users thoroughly

In contrast to one-time purchases, alterations in a recurring revenue model can influence an app's financial health for extended periods, ranging from weeks to years. Even minor modifications can accumulate over time, resulting in notable shifts in revenue.

Therefore, when experimenting with Qonversion, you might consider halting the exposure of new users to the A/B test without ending the experiment altogether.

We advise using the **Pause** button if this situation applies to you. By doing so, Qonversion:

* Continues to send variant-related data to your app for users already involved in the test.
* Sets the traffic allocation percentage to zero, ensuring the A/B test impacts no new users.

<Note>
  Keep in mind: devices that fetch a config while the experiment is paused are evaluated and recorded as excluded. When you resume by raising the traffic level back, those users are **not** re-admitted — only users the experiment has never evaluated join the test. See [Changing experiment traffic mid-flight](/docs/remote-config-targeting#changing-experiment-traffic-mid-flight).
</Note>

<img alt="" />

***

What’s Next

* [Stop experiments](finish-experiment)


# Overview
Source: https://documentation.qonversion.io/docs/paywall-experiments

A/B testing to validate your monetization hypothesis for every paywall element from UI to pricing

Qonversion Experiments are designed for revenue-focused A/B testing for subscription apps to quickly discover if **new pricing, paywall UI, or even new onboarding flow positively impacts your app's revenue**. Qonversion Experiments can be used with your existing subscription payments flow. You can start running advanced subscription app experiments to validate your growth hypothesis in under 30 minutes.

<img alt="" />

## 1. Flexible variants configuration

Our goal is to provide as flexible variants configuration as possible:

* Experiments' in-app values allow you **to set up any appearance of your app's paywall** and even the onboarding steps before the paywall if required.
* Variant weights allow you to decide what share of your users are exposed to each variant. **You are not limited to a default evenly split strategy**.

Assignments are sticky: if you change variant weights or the traffic level mid-flight, existing users keep their groups — the new weights apply only to users admitted afterward. See [Changing experiment traffic mid-flight](/docs/remote-config-targeting#changing-experiment-traffic-mid-flight).

Learn more about [variant configuration](launch-experiments#2-configure-and-test-variants).

<img alt="" />

## 2. Target the right user segments

Qonversion A/B testing offers flexible user segmentation:

* Test hypotheses for **specific countries** to find the most effective pricing strategy.
* Target either **new users** or **particular subscription owners** to determine which introductory offers and upgrades work best.
* Run A/B testing for a specific share of your active users to be able to run **several experiments simultaneously**.
* And [other options](launch-experiments#segment-your-users).

## 3. Analyze experiment results

We believe each experiment should be analyzed in two ways:

* With **a strict focus on the primary metric** you aim to improve. Avoiding data peeking and reducing correlated metrics noise are crucial to making accurate decisions during data collection.
* With convenient access to all the data including all relevant subscription metrics. So you can be 100% sure when you accept or reject the hypothesis.

<img alt="" />

Learn more about how we help [analyse experiments](analyse-experiment).

***

What’s Next

* [Launch experiments](launch-experiments)


# PostHog
Source: https://documentation.qonversion.io/docs/posthog

Send in-app subscription and purchases events to PostHog

Qonversion sends all revenue events, including purchases in your app, subscriptions after free trials, renewals, and even refunds, to your PostHog account. This allows you to match your user behavior with their payment history in PostHog and inform your product decisions.

## 1. Setup the SDKs

1. Make sure you have PostHog SDK installed. More about the PostHog SDKs read [here](https://posthog.com/docs/libraries).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Attribute events sent from Qonversion and events received from the PostHog SDK to the same user by setting the same user ID to PostHog that you set to Qonversion SDK using the [setProperty](user-properties) method.

<CodeGroup>
  ```swift Swift theme={null}
  posthog.identify("yourSideUserID")
  ```

  ```kotlin Kotlin theme={null}
  PostHog.identify("yourSideUserID")
  ```

  ```java Java theme={null}
  PostHog.identify("yourSideUserID", null, null);
  ```

  ```javascript React Native theme={null}
  posthog.identify("yourSideUserID");
  ```

  ```dart Flutter theme={null}
  await Posthog().identify(userId: "yourSideUserID");
  ```

  ```csharp Unity theme={null}
  await PostHog.IdentifyAsync("yourSideUserID");
  ```

  ```typescript Capacitor theme={null}
  await Posthog.identify({ distinctId: "yourSideUserID" });
  ```
</CodeGroup>

<Warning>
  If your events from Qonversion do not attribute to users in PostHog, please check that you are setting user IDs correctly with the SDK.
</Warning>

**→ [Read more about user identifiers here](user-identifiers)**

## 2. Configure the PostHog Integration

1. Navigate to your PostHog project Settings, and copy your Project API Key.

2. Navigate to the Integrations section in your Qonversion project, select PostHog, and provide the API Key.

3. If your PostHog account is hosted on EU servers, switch your region settings to Europe in the Qonversion PostHog integration settings.

4. Choose which event categories to forward: Subscriptions, Trials, Purchases, and Refunds.

5. Select your preferred revenue reporting option: Gross revenue or Proceeds (after store fees).

**→ [Read more about tracked events here](integrations-overview#tracked-events)**

<Check>
  ### Done!

  Now Qonversion will start sending in-app purchases and subscriptions data to your PostHog account.
</Check>

***

[OneSignal](onesignal)

[Pushwoosh](pushwoosh)


# Product Blocks
Source: https://documentation.qonversion.io/docs/product-blocks

Product block templates for subscription and purchase selection screens. Each template includes two products (yearly and monthly) with automatic select-product state handling.

All Product Block templates support:

* **Select Product action** — automatically linked to each product container
* **Default/Selected states** — visual feedback when user selects a product
* **Product variables** — price, period, and other dynamic data

***

### Single Product

A single product card — use as a building block or for single-option screens.

<img alt="single-product" />

***

### Column Simple 1

Vertical list layout with title on the left, price on the right, and optional badge overlay.

<img alt="" />

***

### Column Simple 2

Vertical list with centered content and period labels.

<img alt="" />

***

### Column Simple 3

Compact vertical cards with checkbox selection indicators.

<img alt="" />

***

### Column Complex 1

Full-featured card with savings calculations, trial info, and detailed pricing.

<img alt="" />

***

### Column Complex 2

Rich cards with multiple data points and comparison-friendly layout.

<img alt="" />

***

### Tile 1

Side-by-side cards with radio selection indicators.

<img alt="" />

***

### Tile 2

Compact horizontal tiles with centered content.

<img alt="" />

***

### Tile 3

Rich horizontal tiles with badges and descriptions.

<img alt="" />

***

### With Features 1

Product card with icon-based feature list and optional promotional offer.

<img alt="" />

***

### With Features 2

Detailed comparison cards with comprehensive feature breakdowns.

<img alt="" />

***

### Product Slider

A horizontal carousel of product cards with optional badges, pricing, descriptions, and CTA buttons. Ideal for showcasing multiple subscription options in a swipeable format.

<img alt="" />

**Features:**

* Swipeable product cards
* Optional "Best Value" or promotional badges
* Price and description display
* CTA button per product
* Automatic select-product state handling
* Autoplay with configurable timing

**Use for:**

* Multiple subscription tier comparison
* Promotional offer showcases
* Plan browsing with detailed cards

***

***

[Components](components)

[Social Proof](social-proof)


# Product Setup & Store Connection
Source: https://documentation.qonversion.io/docs/product-setup-store-connection-1

Connect your in-app products from App Store, Google Play, Stripe, or Paddle so they can be used in the No-Code Builder.

## 1. Add Products

*(Optional, but recommended for paywalls)*

If your screen involves in-app purchases or subscriptions, you'll need to create products in your Qonversion project first.

* These products will appear in the Builder’s dropdown for easy linking.
* If you’re only designing onboarding or feature-explainer screens, you can skip this step for now.

You can create products directly from the No-Codes section in your dashboard or from the [Entitlements Section](create-products).

To add products for your screen:

1. Go to **Dashboard** → **No-Codes** → **Getting Started**
2. Scroll to the **Add Products** section
3. Click **Add Product** and fill in the details (Product ID, Store, Type, Duration, Price)

> Learn more about [Entitlements](create-products)

<img alt="" />

***

## 2. Connect Stores

Connecting your Apple App Store and Google Play accounts enables:

* Real-time subscription status tracking
* Purchase validation and fraud protection
* In-depth analytics on conversion, revenue, and retention

Setup typically takes under 10 minutes with our step-by-step guides.

You can connect your store in two ways:

From **No-Codes Section**

1. Go to **Dashboard** → **No-Codes** → **Getting Started**
2. Scroll to **Store Connection**
3. Choose your store (App Store or Google Play)
4. Follow the setup prompts to authorize the connection

Or [follow this guide](quickstart#2-create-a-project-and-register-your-app) to connect stores from **Settings** and learn more.

<img alt="" />

***

## 3. Using Products in the Builder

In the No-Code Builder, you can use products in several ways:

* **Canvas Settings** – Set a **Default Product** that’s automatically selected when the screen is displayed.
* **Actions** – Components like Containers and Buttons include action settings such as *Make a Purchase* or *Select Product*.
* **Text Variables** – Dynamically insert product **names**, **prices**, or other attributes.

Products will appear automatically in the dropdown, ready to bind:

* Display name
* Price *products.weekly.price*
* Trial duration or period
* Currency

You can use multiple products in a single paywall (e.g., monthly and annual options).

> Learn more about [Variables](variables-1)

<img alt="" />

***

## Sync Updates

Whenever you change product prices or configurations in your store, Qonversion automatically syncs them. No need to republish screens — product data updates dynamically.

***

[Installation](installation)

[Creating Screens](getting-started)


# Properties Reference
Source: https://documentation.qonversion.io/docs/properties-reference

Every component in the No-Code Builder has configurable properties that define how it looks, behaves, and interacts with other elements.

This guide lists all available property types, explains how they work, and shows which components support them.

Use it as a universal reference when customizing screens or troubleshooting layout behavior.

***

## Property Overview

| **Property**                            | **Description**                                                                                          | **Supported Components**                                     |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Action**                              | Defines what happens when a component is tapped or clicked.                                              | Button, Container, Product, Badge, Icon                      |
| **Typography**                          | Sets font family, size, weight, color, decorations, spacing, case and alignment for text elements.       | Heading, Text, Button, all container-based components        |
| **Alignment**                           | Controls how child components are aligned within a parent container. Direction depends on parent layout. | All components                                               |
| **Position**                            | Defines element positioning (Static, Relative, Absolute, Fixed, Sticky).                                 | All components except for Badge                              |
| **Layout (Direction)**                  | Sets stacking direction (Vertical ↓ or Horizontal →).                                                    | All container-based components                               |
| **Distribution**                        | Defines spacing logic between child elements (Start, Center, End, Space Between, Space Around, Evenly).  | All container-based components                               |
| **Wrap**                                | Toggles whether children wrap to a new line.                                                             | All container-based components                               |
| **Gap**                                 | Sets consistent spacing between child components.                                                        | All container-based components                               |
| **Size (Width / Height)**               | Controls sizing: Fill, Fit Content, Auto, or Fixed values.                                               | All components                                               |
| **Max / Min Size**                      | Restricts maximum or minimum width and height.                                                           | All components                                               |
| **Spacing (Margin / Padding)**          | Defines internal (padding) and external (margin) spacing.                                                | All container-based components                               |
| **Background**                          | Adds solid color, gradient, or image backgrounds.                                                        | All components                                               |
| **Border**                              | Controls border width, color, and corner radius.                                                         | All components                                               |
| **Shadow**                              | Adds soft elevation shadows for depth.                                                                   | All components                                               |
| **Selected State**                      | Provides alternate styling when an element is selected (used with Select Product action).                | Container, Product (with assigned action **Select Product**) |
| **Visibility**, **Opacity**, **Radius** | Toggles whether a component is visible or hidden on screen.                                              | All components                                               |
| **Variables**                           | Displays dynamic values such as product prices, durations, or currency.                                  | Text, Heading, and text-containing components (e.g. Badge)   |
|                                         |                                                                                                          |                                                              |

***

## Layout & Position Properties

| **Property**     | **Description**                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Direction**    | Defines how child elements are stacked — vertically or horizontally.                                                  |
| **Distribution** | Controls alignment within available space (Start, Center, End, Space Between, Space Around, Evenly).                  |
| **Alignment**    | Positions child components along the cross-axis (horizontal if layout is vertical, vertical if layout is horizontal). |
| **Wrap**         | Allows child components to wrap into multiple rows or columns.                                                        |
| **Gap**          | Adds uniform spacing between all direct child elements.                                                               |
| **Position**     | Determines how a component is placed relative to others:- **Static** – follows normal layout flow                     |

* **Relative** – offsets from default position
* **Absolute** – positioned relative to parent container
* **Fixed** – sticks to screen while scrolling
* **Sticky** – toggles between relative/fixed depending on scroll |

***

## Size & Spacing Properties

These define how big your components appear and how they interact with surrounding elements.

| **Property**       | **Description**                                     |
| ------------------ | --------------------------------------------------- |
| **Width / Height** | Choose from:- **Fill** – occupy all available space |

* **Fit Content** – match child size
* **Auto** – adapt dynamically
* **Fixed** – set explicit pixel or % value |
  \| **Max / Min Width & Height** | Define boundaries for responsiveness.                                                                                                                               |
  \| **Margin**                   | External spacing between the component and neighboring elements.                                                                                                    |
  \| **Padding**                  | Internal spacing between the component’s edges and its content.                                                                                                     |

***

## Typography Properties

Text-related styling and variable configuration.

| **Property**           | **Description**                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------- |
| **Font Family**        | Choose from 20 + fonts (System Font, Inter, SF Pro, Roboto, Lato, Poppins, etc.).     |
| **Font Size & Weight** | Adjust headline or body emphasis.                                                     |
| **Text Color**         | Set color for all text inside the component.                                          |
| **Alignment**          | Align text left, center, or right.                                                    |
| **Variables**          | Insert dynamic text via macros — for example: products.product\_id.price\_per\_month. |

***

## Visual Styling Properties

Used to adjust background, border, and visual depth of your components.

| **Property**   | **Description**                                |
| -------------- | ---------------------------------------------- |
| **Background** | Apply a solid color, gradient, or image fill.  |
| **Border**     | Set border width, color, and corner radius.    |
| **Radius**     | Set border Radius.                             |
| **Shadow**     | Add soft drop shadows for elevated appearance. |
| **Opacity**    | Adjust overall component transparency.         |

***

## Behavioral Properties

Properties that define interactivity, visibility, and logic.

| **Property** | **Description**                                   |
| ------------ | ------------------------------------------------- |
| **Action**   | Defines what happens on tap/click:- Make Purchase |

* Select Product
* Open URL
* Go to Page
* Go to Screen and more |
  \| **Selected State** | Available when “Select Product” action is used — customize active visuals (background, border, icons, etc.).       |
  \| **Visibility**     | Show / Hide component                                                                                              |

***

## Variables & Dynamic Content

Variables let you display real-time product data in text or buttons. They automatically update when prices, currencies, or trial durations change in the store

| **Example Variable**                   | **Description**                                |
| -------------------------------------- | ---------------------------------------------- |
| products.product\_id.price\_per\_month | Displays the monthly price of a product.       |
| products.product\_id.price\_per\_year  | Displays the annual price.                     |
| products.product\_id.trial\_duration   | Shows the trial period (e.g., “7 days free”).  |
| products.product\_id.currency\_symbol  | Displays the currency symbol (\$, €, £, etc.). |

<Info>
  You can use variables inside Text, Heading, or Button labels.
</Info>

***

### Best Practice Summary

* **Start with layout:** direction, distribution, and gap.
* **Set spacing early:** consistent padding makes responsive scaling predictable.
* **Style at the container level:** use background / border / shadow to visually group sections.
* **Define actions clearly:** combine Select Product + Selected State for interactive paywalls.
* **Preview across devices:** ensure responsive alignment under Safe Area (20 px h, 59 px top, 34 px bottom).

***

[AI Image Generation](ai-image-generation)

[Variables](variables-1)


# Purchase Loader
Source: https://documentation.qonversion.io/docs/purchase-loader

Show a custom loader while a purchase is processing, instead of the SDK's default system spinner.

When a user taps a purchase or restore button on a No-Code screen, the SDK shows a native loading spinner until the store finishes processing the payment and Qonversion validates the receipt. The **Purchase Loader** lets you replace that default spinner with your own — a styled spinner or a Lottie animation — configured entirely in the Builder, so the loading state matches your paywall's design.

<Info>
  The Purchase Loader is **off by default**. When it's off, nothing changes — the SDK keeps showing its standard native loader.
</Info>

## Enabling the Purchase Loader

1. Open your screen in the Builder and go to **Settings → General**.
2. Find the **Purchase loader** card and turn on **Use a custom purchase loader**.
3. Pick a loader type — **Spinner** or **Lottie animation** — and style it.

The loader is shown as an overlay on top of the screen for the entire purchase window: from the moment the purchase starts, through store processing, until entitlements are returned (or the purchase fails).

## Loader types

### Spinner

A lightweight, built-in animated spinner. You can set:

* **Color** — the spinner's accent color.
* **Spinner style** — choose between **Ring**, **Dots**, or **Bars**.

A live **Preview** shows exactly how it will look on the screen.

### Lottie animation

Use your own [Lottie](no-code-component-lottie-src) animation for a fully branded loader.

* Click **Select or upload** to pick an animation from your project's asset gallery, upload a `.json` / `.lottie` file, or paste a link.
* **Speed** — play the animation faster or slower (0.1×–3×).
* **Loop animation** — repeat the animation for as long as the purchase is processing (recommended, since processing time varies).

A **Preview** renders the animation with your chosen speed and background.

## Background color

Both loader types are shown over a full-screen backdrop. Set the **Background color** (with transparency) to dim or hide the screen behind the loader while the purchase is in progress.

## SDK version requirement

<Warning>
  The custom Purchase Loader requires **Qonversion iOS SDK 6.13.0+** or **Android NoCodes 1.10.0+**.

  On older SDK versions the app's **native loader is shown on top of your custom one** (a double loader), because the SDK doesn't yet know the screen renders its own. Users on the current SDK see only your custom loader. Make sure your app ships a supported SDK version before relying on this feature.
</Warning>

## Good to know

* **The system payment sheet still covers the loader while it's up.** During the native Apple/Google payment confirmation sheet, the OS renders on top of everything — your loader (like the default one) is hidden behind it. It becomes visible again during the post-sheet receipt-validation window, which is where a branded loader adds the most value (this can range from under a second to several seconds on a slow network).
* **Republish to apply changes.** The loader is baked into the published screen. After changing its settings, **publish the screen** so devices pick up the new loader.

<Tip>
  Keep Lottie loaders short and set to loop — the purchase-processing time isn't fixed, so a looping animation reads better than a one-shot one that finishes mid-wait.
</Tip>


# Pushwoosh
Source: https://documentation.qonversion.io/docs/pushwoosh

Send in-app subscription events to Pushwoosh to win back your subscribers

Qonversion sends [subscription events](integrations-overview#tracked-events) to Pushwoosh to help you run customer-centric messaging to users who cancel their subscriptions. A personalized push notification with a special offer can significantly uplift your app revenue for this particular scenario.

## 1. Setup the SDKs

1. Make sure you have Pushwoosh SDK installed. More about the Pushwoosh SDKs you can find on the platform-specific pages: [IOS](https://docs.pushwoosh.com/platform-docs/pushwoosh-sdk/ios-push-notifications), [Android](https://docs.pushwoosh.com/platform-docs/pushwoosh-sdk/android-push-notifications) and [Cross-platform](https://docs.pushwoosh.com/platform-docs/pushwoosh-sdk/cross-platform-frameworks).

2. Set Qonversion SDK by following [installing the SDK guide](install-sdk).

3. To attribute sent from Qonversion events to a particular Pushwoosh user, set Pushwoosh Hardware ID (HWID):

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.pushWooshHwId, value: Pushwoosh.sharedInstance().getHWID())
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyPushWooshHwId value:[[Pushwoosh sharedInstance] getHWID]];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.PushWooshHwId, Pushwoosh.getInstance().getHWID());
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.PushWooshHwId, Pushwoosh.getInstance().getHWID())
  ```

  ```dart Flutter theme={null}
  String hwid = await Pushwoosh.getInstance.getHWID;
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.pushWooshHwId, hwid);
  ```

  ```typescript React Native theme={null}
  Pushwoosh.getHwid(
    function(hwId) {
      Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.PUSH_WOOSH_HW_ID, hwId);
    }
  );
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.PushWooshHwId, Pushwoosh.Instance.HWID);
  ```

  ```typescript Cordova theme={null}
  pushwoosh.getPushwooshHWID(
    function(hwId) {
      Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.PUSH_WOOSH_HW_ID, hwId);
    }
  );
  ```

  ```typescript Capacitor theme={null}
  pushwoosh.getPushwooshHWID(
    function(hwId) {
      Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.PUSH_WOOSH_HW_ID, hwId);
    }
  );
  ```
</CodeGroup>

4. Set Pushwoosh userId (if already not), then set it to qonversion user's property `.pushwooshUserId`.

<CodeGroup>
  ```swift Swift theme={null}
  Pushwoosh.sharedInstance.setUserId("yourSideUserID")
  Qonversion.shared().setUserProperty(.pushwooshUserId, value: "yourSideUserID")
  ```

  ```objectivec Objective-C theme={null}
  [[Pushwoosh sharedInstance] setUserId:@"yourSideUserID"];
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyPushwooshUserId value:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  Pushwoosh.getInstance().setUserId("yourSideUserID");
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.PushwooshUserId, "yourSideUserID");
  ```

  ```kotlin Kotlin theme={null}
  Pushwoosh.getInstance().setUserId("yourSideUserID")
  Qonversion.shared.setUserProperty(QUserPropertyKey.PushwooshUserId, "yourSideUserID")
  ```

  ```dart Flutter theme={null}
  Pushwoosh.getInstance.setUserId('yourSideUserID');
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.pushwooshUserId, 'yourSideUserID');
  ```

  ```typescript React Native theme={null}
  Pushwoosh.setUserId('yourSideUserID');
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.PUSH_WOOSH_USER_ID, 'yourSideUserID');
  ```

  ```csharp Unity theme={null}
  Pushwoosh.Instance.SetUserId("yourSideUserID");
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.PushwooshUserId, "yourSideUserID");
  ```

  ```typescript Cordova theme={null}
  pushwoosh.setUserId('yourSideUserID');
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.PUSH_WOOSH_USER_ID, 'yourSideUserID');
  ```

  ```typescript Capacitor theme={null}
  pushwoosh.setUserId('yourSideUserID');
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.PUSH_WOOSH_USER_ID, 'yourSideUserID');
  ```
</CodeGroup>

## 2. Configure the Pushwoosh integration

1. Navigate to your [Pushwoosh dashboard](https://app.pushwoosh.com/projects) and collect the following keys:

   1. **Pushwoosh application code** (XXXXX-XXXXX). It can be found right below the name of your application.
   2. **Device API Token**. It can be found in Settings -> API Access. You can learn more about the access token [in this guide](https://docs.pushwoosh.com/platform-docs/api-reference/api-access-token).

   <img alt="" />

2. Navigate to the [Integrations](https://dash.qonversion.io/app/integration/) section of your Qonversion project, select [Pushwoosh](https://dash.qonversion.io/app/integration/create?name=pushwoosh), provide the **Pushwoosh Application Key** and **Device API Token**, and click Save.

<img alt="" />

3. You can use the default event names provided by Qonversion or change them as you need.

**→[Read more about tracked events here](integrations-overview#tracked-events)**

<Check>
  ### Done

  Now Qonversion starts sending in-app purchases and subscription data to your Pushwoosh account.
</Check>

## Event Payload

In case you need details about data sent to Pushwoosh, follow the example below:

<CodeGroup>
  ```json JSON theme={null}
  {
    "hwid": "8f65b16df378e7a6bece9614e1530",
    "userId": "[email protected]",
    "application": "XXXXX-CF22A",
    "auth": "bsu5wJmYRcHFT...WVqW",
    "event": "subscription_started",
    "timestampUTC": 1706771191,
    "attributes": {
      "event_name": "subscription_started",
      "user_id": "QON_9c0d54c7d56f4d46a37d86e1c1a",
      "custom_user_id": "",
      "identity_id": "",
      "advertiser_id": "3c226994-3ded-4841-a031-c4637e78",
      "time": null,
      "created_at": 123,
      "product_id": "product_id",
      "revenue.value": 70,
      "revenue.currency": "USD",
      "revenue.value_usd": 70,
      "revenue.proceeds_rate": 70,
      "revenue.is_proceed": 1,
      "price.value": 100,
      "price.value_usd": 100,
      "price.currency": "USD",
      "transaction.transaction_id": null,
      "transaction.original_transaction_id": null,
      "transaction.expires": null,
      "transaction.grace_period_expires": null,
      "device_id": "",
      "app_version": "",
      "sdk_version": "",
      "environment": "sandbox",
      "platform": "iOS",
      "ip": "",
      "property.custom_user_property_1": "value_1",
      "property.custom_user_property_2": "value_2"
    }
  }
  ```
</CodeGroup>

### See also

Pushwoosh API reference

[https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent](https://docs.pushwoosh.com/developer/api-reference/user-centric-api#postevent)

***

[OneSignal](onesignal)

[SplitMetrics Acquire](splitmetrics)


# Welcome
Source: https://documentation.qonversion.io/docs/qonversion-platform

Developer-focused overview of the Qonversion platform: SDKs, APIs, No-Code Builder, A/B testing, Remote Configs, and integrations.

## What is Qonversion?

<img alt="Qonversion Overview" />

<CardGroup>
  <Card title="SDKs & APIs" icon="code" href="/docs/quickstart">
    Process in-app and web purchases with comprehensive SDKs and APIs
  </Card>

  <Card title="No-Code Builder" icon="paintbrush" href="/docs/no-codes">
    Create and manage in-app paywalls and screens *without code changes* using visual tools
  </Card>

  <Card title="A/B Testing" icon="flask" href="/docs/paywall-experiments">
    Experiment with paywalls, pricing, and offers to optimize conversion rates
  </Card>

  <Card title="Remote Configs" icon="sliders" href="/docs/remote-config">
    Dynamic updates to app behavior and paywall content without app store releases
  </Card>

  <Card title="Apple Ads Attribution" icon="bullseye" href="/docs/apple-search-ads-analytics">
    Analyze campaign and keyword-level user acquisition performance
  </Card>

  <Card title="Integrations" icon="plug" href="/docs/integrations-overview">
    Out-of-the-box integrations with analytics, attribution, and marketing platforms
  </Card>
</CardGroup>

## Essential Links

* [Quick Start Guide](quickstart) -- A step-by-step guide to swiftly begin using Qonversion's core features.
* [SDK Setup](install-sdk) -- Instructions on how to install and configure the Qonversion SDK.
* [API Reference](/reference/overview) -- Comprehensive details on Qonversion's API endpoints and their usage.
* [Sample Apps](sample-apps) -- Example applications demonstrating Qonversion integration.
* [Tutorials](tutorials) -- Step-by-step guides to help you utilize Qonversion's features.
* [Migration Guide](migrating-subscriptions) -- Guidance for migrating subscriptions to Qonversion from other platforms.
* [Stripe Integration](stripe-integration) -- Instructions on integrating Stripe with Qonversion for payments.
* [Paddle Integration](paddle-integration) -- Instructions on integrating Paddle with Qonversion for web payments.
* [Troubleshooting](troubleshooting) -- Solutions and tips for resolving common issues.


# [Aug 2023] Migration Guide
Source: https://documentation.qonversion.io/docs/qonversion-sdk-major-version

We have released a major update for our Qonversion SDK with several new features, improvements, and design fixes. This article provides the necessary steps to migrate from previous SDK versions to the ones displayed in the table below:

| Platform     | Major version |
| ------------ | ------------- |
| iOS          | 5.+           |
| Android      | 6.+           |
| Flutter      | 7.+           |
| React Native | 6.+           |
| Unity        | 6.+           |

Choose your platform to continue:

* [iOS 5.+ migration guide](ios-5-migration-guide)
* [Android 6.+ migration guide](android-6-migration-guide)
* [Flutter 7.+ migration guide](flutter-7-migration-guide)
* [React Native 6.+ migration guide](react-native-6-migration-guide)
* [Unity 6.+ migration guide](unity-6-migration-guide)
* [Cordova 4.+ migration guide](cordova-4-migration-guide)
* [Web 1.+ migration guide](web-1-migration-guide)

***

[Cordova SDK 4.x to 5.x migration guide](cordova-5-migration-guide)

[iOS 5.+ migration guide](ios-5-migration-guide)


# [Jan 2024] Migration guide. Google Play Billing Library 6.
Source: https://documentation.qonversion.io/docs/qonversion-sdk-major-version-copy

We have released a major update to our Android and cross-platform Qonversion SDKs with new Google Play Billing Library support, several improvements, and various design fixes. This article enumerates the steps necessary to migrate from previous SDK versions to the ones displayed in the table below:

| Platform     | Major version |
| ------------ | ------------- |
| Android      | 7.x           |
| Flutter      | 8.x           |
| React Native | 7.x           |
| Unity        | 7.x           |
| Cordova      | 5.x           |

Choose your platform to continue:

* [Android SDK 6.x to 7.x migration guide](android-7-migration-guide)
* [Flutter SDK 7.x to 8.x migration guide](flutter-8-migration-guide)
* [React Native SDK 6.x to 7.x migration guide](react-native-7-migration-guide)
* [Unity SDK 6.x to 7.x migration guide](unity-7-migration-guide)
* [Cordova SDK 4.x to 5.x migration guide](cordova-5-migration-guide)

<Info>
  ### More Resources in Our Blog
</Info>

* [Google Play Billing Library 7](https://qonversion.io/blog/google-play-billing-7/)
* [Google Play I/O 2024 Updates](https://qonversion.io/blog/google-play-i-o-2024-updates-for-app-developers/)
* [Google Play Billing Library 6](https://qonversion.io/blog/whats-new-in-google-play-billing-library-6/)

***


# Overview
Source: https://documentation.qonversion.io/docs/quickstart

Quick start guide that walks you through setting up Qonversion: choose a mode, create a project, install the SDK, and implement Analytics or Subscription Management Mode.

Setting up Qonversion takes four steps: choose a mode, create a project and register your app, install the SDK, and implement the mode you chose. Follow the steps below in order.

<Steps>
  <Step title="Choose the Qonversion mode you want to implement">
    Qonversion offers two modes. Pick one before you start — the SDK setup and the amount of code you write differ between them.

    * **Analytics Mode (Observer)** — implement in about 20 minutes to get best-in-class mobile subscription analytics and leverage subscription data with integrations and webhooks. It does **not** manage purchases or entitlements for you.
    * **Subscription Management Mode** — required if you want Qonversion to fetch product data, make purchases, and check subscription status, including managing cross-platform user access. Expect 2+ hours to set up.

    The comparison of the features available with each mode is presented below:

    | Features                                                                                          | Analytics Mode (Observer) | Subscription Management Mode |
    | ------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------- |
    | Implementation time                                                                               | **20 minutes**            | **2+ hours**                 |
    | Subscription Analytics                                                                            | ✅                         | ✅                            |
    | Real-time Monitoring                                                                              | ✅                         | ✅                            |
    | Integrations (send data to other platforms)                                                       | ✅                         | ✅                            |
    | Apple Search Ads Insights                                                                         | ✅                         | ✅                            |
    | Raw Data Export                                                                                   | ✅                         | ✅                            |
    | Webhooks                                                                                          | ✅                         | ✅                            |
    | Subscriber Details & Custom User Properties                                                       | ✅                         | ✅                            |
    | Paywall experiments                                                                               | ✅                         | ✅                            |
    | Subscription Management (fetch in-app product data -> make purchase -> check subscription status) | ❌                         | ✅                            |
  </Step>

  <Step title="Create a project and register your app">
    1. Navigate to the [New Project](https://dash.qonversion.io/app/start/create) page and provide a new project's name. One project in Qonversion supports iOS, Android, and Web apps.

    2. In [Settings](https://dash.qonversion.io/project/settings), select the platform for your app and provide platform-specific data:

       * **iOS App**:
         1. App-Specific Shared Secret — you can find more details [here](ios-app-store-info-fields#2-generate-the-app-specific-shared-secret).
         2. Your app's App Store ID. To get your app's App Store ID, navigate to the Apps tab in your App Store Connect account. Click on your app. You can see the App ID in the URL.
       * **Android App**:
         1. Service Account Key credentials — you can find more details [here](android-store-setup).
         2. Android package name.
       * **Stripe App**: Please follow [this guide](stripe-integration) to connect Stripe to Qonversion.

    3. Get your Qonversion project key. You can find your Qonversion project key in the [Settings](https://dash.qonversion.io/project/settings) section of Qonversion. You will need this key to [configure the SDKs](install-sdk). The project key is not the same as a store shared secret or service account key.

       <img alt="" />

    <Info>
      Please note, it may take up to 24 hours for your Google service credentials to work properly with the Android Developer API. You may see "Please provide valid JSON credentials" during the first 24 hours until the credentials start working correctly.
    </Info>
  </Step>

  <Step title="Install the SDK">
    Install the Qonversion SDK for your platform:

    → [iOS SDK](ios-sdk-setup) → [Android SDK](android-sdk) → [Flutter SDK](flutter-sdk) → [React Native SDK](react-native-sdk) → [Unity SDK](unity-sdk) → [Cordova Plugin](cordova) → [Capacitor Plugin](capacitor) → [Web SDK](web-sdk)

    <Info>
      ### Kids Mode SDKs

      If you are building an app for kids, it is necessary to follow policies and not collect IDFA, GAID, and other advertisement attributes. For Kids Mode SDK integration follow [this guide](kids-mode-sdk).
    </Info>
  </Step>

  <Step title="Implement Analytics or Subscription Management Mode">
    Use the mode you chose in Step 1 and follow the required option:

    * For **Analytics Mode**, follow [this guide](analytics-mode) (10 more minutes to set everything up).
    * For **Subscription Management Mode**, follow [this guide](subscription-management-mode).
  </Step>
</Steps>

## Additional Resources

→ Check out the [Sample Apps](sample-apps) → Tips on [testing](testing) → [Troubleshooting](troubleshooting) → [Migrating In-App Subscriptions](migrating-subscriptions)

## Next steps

After the SDK is installed and your mode is implemented, wire up the purchase flow and verify access. These steps apply to Subscription Management Mode.

<CardGroup>
  <Card title="Displaying products" icon="grid-2" href="displaying-products">
    Fetch your configured products from Qonversion to build your paywall.
  </Card>

  <Card title="Making purchases" icon="cart-shopping" href="making-purchases">
    Trigger a purchase through the SDK and handle the result and errors.
  </Card>

  <Card title="Check entitlements" icon="circle-check" href="check-permissions">
    Read a user's active entitlements to unlock or gate premium features.
  </Card>

  <Card title="Testing" icon="flask" href="testing">
    Test purchases in the Apple and Google sandbox before going live.
  </Card>
</CardGroup>


# Rate Limits
Source: https://documentation.qonversion.io/docs/rate-limits

Our SDKs include rate limit checks for API requests from the following versions. It's aimed at protecting our API from unexpected DoS attacks from SDKs due to unintended usage.

| Platform     | Version |
| ------------ | ------- |
| iOS          | 5.1.1   |
| Android      | 6.1.1   |
| React Native | 6.1.0   |
| Flutter      | 7.1.0   |
| Unity        | 6.1.0   |
| Cordova      | 4.1.0   |
| Capacitor    | 0.1.0   |

Every endpoint and every set of arguments separate the limits. The count of identical API requests per second is limited to 5. Exceeding this amount will cause an `ApiRateLimitExceeded` error, described [here](handling-errors).

If you receive the error mentioned above, ensure you don't call Qonversion SDK methods multiple times from several threads on each screen/view render method, etc.

***

[Qonversion SDK Errors Details](handling-errors)

[Customers](customers)


# Raw Data Export
Source: https://documentation.qonversion.io/docs/raw-data-reports

Download your raw data for the specific period, schedule report sending to your Email, Slack channel or Webhook.

## To export the data:

Select [Export Data](https://dash.qonversion.io/reports/raw-data) from the menu.

1. Select the period at the top right corner.
2. Select the events sorting option for the export. There are two options available:

* sort by **Transaction date** (date of an event according to app stores)
* sort by **Event receive date** (date of an event detected by Qonversion). Using this option, you can ensure that no new events will appear for the selected period if another export is performed sometime later.

3. Click the **Download** button or send the download link to your email.

<img alt="" />

<Info>
  Generating your export file may take some time, depending on the file size.
</Info>

## Raw Data Export Fields

| Name                 | Description                                                                                                                                                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event Date           | Date and time Qonversion tracked the event                                                                                                                                                                                                      |
| Transaction ID       | Store Transaction ID                                                                                                                                                                                                                            |
| Transaction Date     | App Store transaction date and time                                                                                                                                                                                                             |
| Event Name           | Event name like Subscription Started or Trial Started. [Learn more.](integrations-overview#tracked-events)                                                                                                                                      |
| App Name             | Your App name in Qonversion                                                                                                                                                                                                                     |
| Platform             | iOS or Android                                                                                                                                                                                                                                  |
| App ID               | Your App ID in Qonversion                                                                                                                                                                                                                       |
| Product ID           | Product ID in App Stores                                                                                                                                                                                                                        |
| Subscription Group   | Subscription group in App Stores                                                                                                                                                                                                                |
| Currency             | Currency of the underlying product                                                                                                                                                                                                              |
| Price                | Price of the underlying product                                                                                                                                                                                                                 |
| Proceeds             | Price excluding App Stores commission (-15% or -30%)                                                                                                                                                                                            |
| Price USD            | Price of the underlying product converted to USD                                                                                                                                                                                                |
| Proceeds USD         | Price excluding App Stores commission converted to USD                                                                                                                                                                                          |
| \[Deprecated] Refund | App Store refund date. Follow to *Subscription Refunded* events to understand whether transactions were refunded. *Transaction ID* and *Transaction Date* fields in these events contain the base transaction ID and refund date, respectively. |
| Q User ID            | User ID in generated by Qonversion                                                                                                                                                                                                              |
| User ID              | External user ID set using *CustomUserId* from [User Properties](user-properties#defined-user-properties).                                                                                                                                      |
| Device               | Device type                                                                                                                                                                                                                                     |
| Device ID            | Device ID                                                                                                                                                                                                                                       |
| Locale               | Device language                                                                                                                                                                                                                                 |
| Country              | ISO 3166-1 alpha-2 – two-letter country codes                                                                                                                                                                                                   |
| OS Version           | Operating System version                                                                                                                                                                                                                        |
| Install Date         | Install date and time                                                                                                                                                                                                                           |
| Media source         | Source of the ad (ad provider/advertising network) by which the customer was acquired.                                                                                                                                                          |
| Campaign             | Advertising campaign                                                                                                                                                                                                                            |
| Ad set               | A set of advertising offers                                                                                                                                                                                                                     |
| Ad                   | Advertising offer                                                                                                                                                                                                                               |
| App version          | User's app version                                                                                                                                                                                                                              |
| SDK version          | User's Qonversion SDK version                                                                                                                                                                                                                   |
| User properties      | Attributes you set using [Custom User Properties](user-properties). Example: `{"_q_fb_anon_id": "ZZZZE22V4T-14FF-4562-845E-333V86BATEEE", "_q_custom_user_id": "1555235760300-6102200", "_q_appsflyer_user_id": "1645555760360-6154600"}`       |
| Event Receive Date   | Date the event was received by Qonversion                                                                                                                                                                                                       |

***

[Analytics Overview](analytics-overview)

[Scheduled Reports](scheduled-reports)


# React Native 4.+ migration guide
Source: https://documentation.qonversion.io/docs/react-native-4-migration-guide

Historical migration guide for upgrading the Qonversion React Native SDK to major version 4.+: updated initialization, renamed methods, and revised purchase and entitlement APIs.

## Upgrading version

Increase the dependency version in your package.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json package.json theme={null}
  "react-native-qonversion": "^4.0.0"
  ```
</CodeGroup>

## Initialization

Qonversion React Native SDK 4 contains significant changes in how the library is initialized. We are moving from a static class approach to an instance-based one. Before, you initialized Qonversion using the `launchWithKey` call:

<CodeGroup>
  ```typescript React Native theme={null}
  Qonversion.launchWithKey('projectKey', true);
  ```
</CodeGroup>

Now, instead, you should create a `QonversionConfig` object using `QonversionConfigBuilder` and provide it to the initialization method as follows:

<CodeGroup>
  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  ).build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

Note that instead of providing the `observeMode` flag to the `launchWithKey` call, you now should provide a concrete value from the `LaunchMode` enum depending on which mode you use Qonversion. Also, we've renamed our modes to make them clearer for users:

* "Observe" mode becomes "Analytics" mode,
* "Infrastructure" mode becomes "Subscription Management" mode.

After the initialization, you can access the Qonversion instance whenever you want as follows:

<CodeGroup>
  ```typescript React Native theme={null}
  Qonversion.getSharedInstance();
  ```
</CodeGroup>

So you should replace all your Qonversion calls with the construction above.

Also, if you were using `Qonversion.setDebugMode()` for testing purposes, you should now call the `setEnvironment(Environment.SANDBOX)` method of the `QonversionConfigBuilder`.

As no `launchWithKey` method is available anymore, you won't get `LaunchResult` as a result. The good news is that there are analogues for all the fields you might have been using from there:

* for `uid`, call `userInfo()` and get the `User.qonversionId` from the result,
* for `products` call `products()`,
* for `offerings` call `offerings()`,
* for `permissions`, call `checkEntitlements()`.

## Entitlements

We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

| Version `<4`                | Version 4+                    |
| --------------------------- | ----------------------------- |
| Permission                  | Entitlement                   |
| ProductRenewState           | EntitlementRenewState         |
| PermissionSource            | EntitlementSource             |
| PermissionsCacheLifetime    | EntitlementsCacheLifetime     |
| checkPermissions            | checkEntitlements             |
| UpdatedPurchasesDelegate    | EntitlementsUpdateListener    |
| setUpdatedPurchasesDelegate | setEntitlementsUpdateListener |

The `Entitlement` class contains the same information as the `Permission` with a renaming of the `permissionId` field - now it's named simply `id`. Also, the `startedDate` and `expirationDate` fields were converted from number to `Date`.

There is no `setPermissionsCacheLifetime` method in Qonversion. You should provide `EntitlementsCacheLifetime` to `QonversionConfigBuilder` during the initialization using the `setEntitlementsCacheLifetime` method.

<CodeGroup>
  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
  	.setEntitlementsCacheLifetime(EntitlementsCacheLifetime.YEAR)
  	.build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

## Automation changes

We've also changed the way the `Automations` is used. As in Qonversion, you should use `Automations` via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.

<Info>
  ### You should access the shared instance of `Automations` strictly after you initialize Qonversion, else an exception will be thrown.
</Info>

<CodeGroup>
  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  ).build();
  Qonversion.initialize(config);
  Automations.getSharedInstance().setDelegate(...);
  ```
</CodeGroup>

Also, the methods for working with push notifications were moved from `Qonversion` to `Automations`, so if you were using the following methods:

* `setNotificationsToken`,
* `handleNotification`,
* `getNotificationCustomPayload`, make sure to make calls from the Automations instance instead of the Qonversion one.

## Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

* all the internal classes were moved to the `internal` package, and DTO classes were moved to the `dto` package to make the library file structure more readable;
* the deprecated methods `resetUser` and `setUserId` were removed. `resetUser` was deprecated for a long time, and it did nothing, so there is nothing to replace this call with, remove the call if you were still using it for some reason. `setUserId` should be replaced with the `setProperty` call with `UserProperty.CUSTOM_USER_ID` parameter.
* the `experiments` method was removed along with the `ExperimentInfo` and `ExperimentGroup` classes - we are now working on a new design of A/B experiments;
* added the new method `userInfo`, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
* added new enum values - `OfferingTag.UNKNOWN` and `TrialDuration.UNKNOWN`, which are used when parsing fails;
* the `Property` and `Provider` enum values were changed from numbers to strings;
* the deprecated `Provider.APPLE` value was removed, consider using `Provider.APPLE_SEARCH_ADS` instead;
* the following methods, classes, and values renamings took place:

| Old name                                  | New name                           |
| ----------------------------------------- | ---------------------------------- |
| `addAttributionData`                      | `attribution`                      |
| `checkTrialIntroEligibilityForProductIds` | `checkTrialIntroEligibility`       |
| `setAdvertisingID`                        | `collectAdvertisingId`             |
| `setAppleSearchAdsAttributionEnabled`     | `collectAppleSearchAdsAttribution` |
| `PromoPurchasesDelegate`                  | `PromoPurchasesListener`           |
| `Property`                                | `UserProperty`                     |
| `Provider`                                | `AttributionProvider`              |
| `UserProperty.ADJUST_USER_ID`             | `UserProperty.ADJUST_AD_ID`        |

***

[Flutter 5.+ migration guide](flutter-5-migration-guide)

[Unity 4.+ migration guide](unity-4-migration-guide)


# React Native 6.+ migration guide
Source: https://documentation.qonversion.io/docs/react-native-6-migration-guide

Historical migration guide for upgrading the Qonversion React Native SDK to major version 6.+: renamed entities and methods with a before/after reference for updating your integration.

## Upgrading version

Increase the dependency version in your package.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json package.json theme={null}
  "react-native-qonversion": "^6.0.0"
  ```
</CodeGroup>

## Renamings

In this major version, we have renamed several entities and public methods to make our namings more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade    | After upgrade           |
| ----------------- | ----------------------- |
| `UserProperty`    | `UserPropertyKey`       |
| `setUserProperty` | `setCustomUserProperty` |
| `setProperty`     | `setUserProperty`       |

## User properties changes

As mentioned above, we have renamed the`UserProperty` enum to `UserPropertyKey`. It was made to release the name `UserProperty` for a class, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```typescript React Native theme={null}
  try {
    const userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach(userProperty => {
      console.log('User property - key:' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

`UserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                 | Description                                                                                              |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `getProperty`        | `key` - string            | Searches for a property with the given property `key` in all properties list                             |
| `getDefinedProperty` | `key` - `UserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `UserPropertyKey` enum with a `CUSTOM` key to represent all the custom properties.

***

[Flutter 7.+ migration guide](flutter-7-migration-guide)

[Unity 6.+ migration guide](unity-6-migration-guide)


# React Native SDK 6.x to 7.x migration guide
Source: https://documentation.qonversion.io/docs/react-native-7-migration-guide

We've upgraded the Google Play Billing Library dependency on Android to version 6 in this release, which has led to major changes in the product and subscription management parts of our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *package.json* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json package.json theme={null}
  "react-native-qonversion": "^7.0.0"
  ```
</CodeGroup>

## Product updates

### Qonversion and Google Play product link changes

Google Play has recently upgraded the structure of their subscription products. We've written about it [in our blog](https://qonversion.io/blog/google-play-billing-library-5-0/). In short, they combined the same subscriptions with different durations into a single subscription with different base plans. In addition, they announced different kinds of offers to base plans, including free trials or introductory prices. In this release, we begin to support those changes.

Previously Qonversion **subscription** products required a Google Play subscription identifier. Now you can also set a specific **base plan** for the subscription. Different base plans of the same subscription can be linked to different Qonversion products. Let's have a look at an example.

Let's say you sell monthly and annual subscriptions in your app, both on Android and iOS. With the previous Qonversion SDK versions, you would specify two Qonversion products (`premium_monthly` and `premium_annual`), two App Store products (`premium_monthly_ios` and `premium_annual_ios`), and two Google Play products (`premium_monthly_android` and `premium_annual_android`). Then you would link those store products to Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_monthly_android`,

`premium_annual` - `premium_annual_ios` and `premium_annual_android`.

With the new Google Play Subscriptions structure, you can create only one subscription for Android - `premium_android` and two base plans for it (`monthly` and `annual`). With this done, you can now use a single subscription for both Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_android` with `monthly` base plan,

`premium_annual` - `premium_annual_ios` and `premium_android` with `annual` base plan.

### Store details for the `QProduct` class

Speaking of the SDK side - the first big part of the changes is the addition of the new `basePlanId` field to `Product` which can be set to the product via Qonversion Dashboard.

We have deprecated the `Product.skuDetails` field, because `SkuDetails` contain information only for backward compatible base plans and are now deprecated in the Google Play Billing Library. Instead, we have added the new `storeDetails` field of type `ProductStoreDetails`, which contains all the store information for the Google Play Product. You can find the specifications of that class [on this page](google-play-product-details).

If `basePlanId` is not specified for a product, it means one of the following:

* it is a one-time (in-app) product that can not have any base plans,
* it is a product that was not updated in the Qonversion dashboard after this version was released,
* it is an iOS-only product.

In the case of the in-app product, both `skuDetails` and `storeDetails` fields will contain information about that in-app. But in the second case, when there is a subscription product without a specified base plan, the `skuDetails` field will contain information about the **backward compatible** base plan, while the `storeDetails` field will only contain common subscription information without base-plan-specific data. It means that you should start using `storeDetails` field for base-plan-specific data (like price, duration, and so on) for Android subscription products only if you've specified their base plan IDs in Qonversion product settings.

### The other `Product` fields changes

Along with the above changes, we have changed the `type` field and removed the `duration` and `trialDuration` fields from the product class. The `type` and `duration` were previously being set via the dashboard, and the `trialDuration` was calculated from the store details and was represented as an enumeration with several common durations. Now, the product `type` is calculated from the store details both for Android and iOS. We've also added the `INTRO` value to `ProductType` to separate `trial` and `intro` products (Android only for now). An `UNKNOWN` value was also added for the cases where we are unable to determine the product type. The `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod`. Both properties are of type `SubscriptionPeriod` and the values are also calculated from the store details for both platforms.

The last thing to note is that we've also changed the `prettyPrice` and `prettyIntrodactoryPrice` fields calculation for Android. Earlier they were calculated from `skuDetails`, while now we first try to use `storeDetails` if possible and only then fall back to `skuDetails`.

### `Product` updates summary

Below is the shortened summary of the `Product` changes:

* new `basePlanId` field, specifying concrete subscription base plan for Google Play subscriptions, added,
* `skuDetails` field deprecated,
* new `storeDetails` field, containing information about Google Play product, added;
* the `type` field is now calculated based on store details both for Android and iOS, instead of the value set via the Qonversion dashboard. The `INTRO` and `UNKNOWN` values were added to `ProductType` to separate cases of trial and intro products (Android only for now) and also the case when we are unable to determine the product type;
* the `duration` and `trialDuration` fields were replaced with `subscriptionPeriod` and `trialPeriod` fields of type `SubscriptionPeriod` with the values calculated from the store details both for Android and iOS;
* the `prettyPrice` and `prettyIntroductoryPrice` fields on Android now prefers `storeDetails` to get the price from, and only then - `skuDetails`.

## Purchase flow updates

In this release, we have changed the `purchase` and `updatePurchase` methods signatures. Previously there were several methods for different sets of arguments. Now we've arranged all those properties into classes - `PurchaseModel` and `PurchaseUpdateModel`, that should be instantiated and provided to the single `purchase` or `updatePurchase` method.

You can create instances of those classes either manually or by using the utility functions `toPurchaseModel` and `toPurchaseUpdateModel` added to the `Product` class.

Below is an example of how the `purchase` flow has changed:

<CodeGroup>
  ```typescript React Native theme={null}
  // Old
  const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().purchaseProduct(product);

  // New
  const purchaseModel: PurchaseModel = product.toPurchaseModel();
  const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().purchase(purchaseModel);
  ```
</CodeGroup>

And an `updatePurchase` flow example:

<CodeGroup>
  ```typescript React Native theme={null}
  // Old
  const entitlement: Map<string, Entitlement> = await Qonversion.getSharedInstance().updatePurchaseWithProduct(product, 'oldProductId');

  // New
  const purchaseUpdateModel: PurchaseUpdateModel = product.toPurchaseUpdateModel('oldProductId');
  const entitlement: Map<string, Entitlement> = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

If you were using only product identifiers, you can create purchase models manually as follows:

<CodeGroup>
  ```typescript React Native theme={null}
  // Old
  const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().purchase('productId');

  // New
  const purchaseModel: PurchaseModel = new PurchaseModel('productId');
  const entitlements: Map<string, Entitlement> = await Qonversion.getSharedInstance().purchase(purchaseModel);
  ```
</CodeGroup>

<CodeGroup>
  ```typescript React Native theme={null}
  // Old
  const entitlement: Map<string, Entitlement> = await Qonversion.getSharedInstance().updatePurchase('newProductId', 'oldProductId');

  // New
  const purchaseUpdateModel: PurchaseUpdateModel = new PurchaseUpdateModel('newProductId', 'oldProductId');
  const entitlement: Map<string, Entitlement> = await Qonversion.getSharedInstance().updatePurchase(purchaseUpdateModel);
  ```
</CodeGroup>

If necessary, you can provide a specific offer for subscription purchase.

<CodeGroup>
  ```typescript React Native theme={null}
  // Specifying offer via the `toPurchaseModel` method:
  const productOfferDetails = ...; // Choose an offer from `storeDetails`
  const purchaseModel = product.toPurchaseModelWithOffer(productOfferDetails);

  // Specifying offer ID via the `toPurchaseModel` method:
  const purchaseModel = product.toPurchaseModel('offer_id');

  // Specifying offer ID via the constructor:
  const purchaseModel = new PurchaseModel('productId', 'offer_id');
  const purchaseUpdateModel = new PurchaseUpdateModel('newProductId', 'oldProductId', 'offer_id');

  // Specifying offer ID after the purchase model creation:
  purchaseModel.offerId = 'offer_id';
  ```
</CodeGroup>

If provided, we will try to find and purchase the offer with the specified ID for the requested Qonversion product. If there is no offer with the specified ID, an error will be returned. If no offer ID is provided for the subscription purchase of Qonversion product with a specified base plan ID, then we will choose the most profitable offer for the client from all the available offers. We calculate the cheapest price for the client by comparing all the trial or intro phases and the base plan. For iOS, old Qonversion products (where the base plan ID is not specified), or in-app products, the offer ID is ignored.

You can also remove any intro/trial offer from the purchase (use only a bare base plan). For that purpose, you should call `removeOffer` method of purchase model:

<CodeGroup>
  ```typescript React Native theme={null}
  purchaseModel.removeOffer();
  ```
</CodeGroup>

## The other changes

* The `checkTrialIntroEligibility` method improved and now detects the eligibility based on store details on Android;
* The `ProductDuration` and `TrialDuration` classes were removed;
* The `ProductType` enum values were changed to meet guidelines;
* The `ProrationMode` enum was removed and replaced with `PurchaseUpdatePolicy` ([read more](making-purchases)).

***

[Flutter SDK 7.x to 8.x migration guide](flutter-8-migration-guide)

[Unity SDK 6.x to 7.x migration guide](unity-7-migration-guide)


# React Native SDK 7.x to 8.x migration guide
Source: https://documentation.qonversion.io/docs/react-native-8-migration-guide

We've upgraded the Google Play Billing Library dependency for Android to version 7 in this release, leading to several changes in our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *package.json* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json package.json theme={null}
  "react-native-qonversion": "^8.0.0"
  ```
</CodeGroup>

## Android deployment upgrades

With the new Google Play Billing Library 7 we've increased our `minSdkVersion` to 21 and `targetSdkVersion` to 34 for Android.

If you were using lower `minSdkVersion` you should upgrade it to 21 to use the latest version of our SDK and Google Play Billing Library. If you have already targeted the 21+ version, you should do nothing.

## Installment plans support

In the latest library version, Google introduces installment plans, when a customer commits to pay for several subsequent subscription periods. In our release, we've added a new field `installmentPlanDetails` to `ProductOfferDetails` with the details of the installment plan if they exist. It contains the following information:

| Field                               | Type | Description                                                               |
| ----------------------------------- | ---- | ------------------------------------------------------------------------- |
| `commitmentPaymentsCount`           | Int  | Committed payments count after a user signs up for this subscription plan |
| `subsequentCommitmentPaymentsCount` | Int  | Subsequent committed payments count after this subscription plan renews   |

We've also added an `isInstallment` flag to `ProductStoreDetails` to check if the current product has an installment plan or not.

Below is an example of those fields usage:

<CodeGroup>
  ```typescript React Native theme={null}
  const products = await Qonversion.getSharedInstance().products();
  const installmentProduct: Product = products['installmentProductId'];
  const storeDetails = installmentProduct?.storeDetails;
  if (storeDetails?.isInstallment) {
    const installmentDetails = storeDetails?.basePlanSubscriptionOfferDetails?.installmentPlanDetails;
    // Use the installment plan information
  }
  ```
</CodeGroup>

## Fallback files

We're happy to introduce the fallback files support in this release to make our system reliability even higher. Fallback files allow your app to work as expected in rare cases of network connection or Qonversion API issues for new users without a cache available. This allows purchases and entitlements to be processed for new users even if the Qonversion API faces issues. This also makes it possible to receive remote configs for cases when the network connection is unavailable.

Fallback files are available both on iOS and Android.

Read more about the fallback files in [the documentation](system-reliability#fallback-files).

## Error codes

In this release, we have added the `QonversionErrorCode` enum with the list of defined Qonversion error codes. Now you can compare any error code with the defined one to check any specific case as follows:

<CodeGroup>
  ```typescript React Native theme={null}
  try {
    await Qonversion.getSharedInstance().purchase(...);
  } catch (e) {
    if (e.code === QonversionErrorCode.STORE_PRODUCT_NOT_AVAILABLE) {
      // The requested product is unavailable for purchase. 
    }
  }
  ```
</CodeGroup>

We've also changed the type of `QonversionError.code` field from `string` to `QonversionErrorCode`.

## The other changes

* Pending purchases support was added for prepaid subscriptions on Android.

***

[Flutter SDK 8.x to 9.x migration guide](flutter-9-migration-guide)

[Unity SDK 7.x to 8.x migration guide](unity-8-migration-guide)


# React Native
Source: https://documentation.qonversion.io/docs/react-native-sdk

Building subscriptions with Qonversion React Native SDK is simple. Learn more about  and  for free now.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/react-native-sdk?label=Latest%20Release)](https://github.com/qonversion/react-native-sdk/releases)

Install Qonversion React Native SDK to validate user receipts, and get in-app subscription analytics and third-party integrations.

## Install via npm

Qonversion SDK package is available on [npm](https://www.npmjs.com/package/@qonversion/react-native-sdk).

<CodeGroup>
  ```bash Terminal theme={null}
  npm install @qonversion/react-native-sdk
  ```
</CodeGroup>

<Info>
  Migrating from `react-native-qonversion` (v9 or earlier)? See the [React Native v10 migration guide](sep-2025-migration-guide-react-native-10) - the package was renamed to `@qonversion/react-native-sdk`.
</Info>

## Extra steps

### iOS

React Native auto-linking handles the native module registration. After installing the package, run `pod install` from your `ios/` folder.

### Android

Include the `BILLING` permission in your `AndroidManifest.xml` file as follows:

<CodeGroup>
  ```xml AndroidManifest.xml theme={null}
  <uses-permission android:name="com.android.vending.BILLING" />
  ```
</CodeGroup>

## Running with Expo

If you are using Qonversion in an Expo app you will have to create [Development Builds](https://docs.expo.dev/develop/development-builds/create-a-build/).

<Warning>
  ### Solving `TypeError: null is not an object (evaluating ‘RNQonversion.storeSDKInfo’)`

  As Qonversion React Native SDK contains native modules, there is no option to run your app using Expo Go. Make sure you use Development Builds as described above to solve this issue.
</Warning>

## Kids Mode for Qonversion React Native SDK

In case you are building an App for Kids, [follow this guide](kids-mode-sdk) to learn about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# Refund Keeper
Source: https://documentation.qonversion.io/docs/refund-keeper

Stop losing money on refunds with Qonversion Refund Keeper. Automate data sharing with Apple to reduce unjustified refunds and protect your earnings.

**Refund Keeper** helps Qonversion users reduce revenue loss from Apple’s App Store refunds by automating the refund process. It ensures Apple receives the necessary app usage data to make fair refund decisions — helping developers retain more revenue while staying compliant with Apple’s policies.

<iframe title="Qonversion Refund Keeper overview" />

## What is Refund Keeper?

When a user requests a refund for an in-app purchase, Apple reviews their app usage data to determine whether to approve or deny it. If the subscription was actively used, Apple may still approve the refund unless the developer provides additional data to justify rejecting it.

**Refund Keeper** automates this process, giving Apple a complete picture of how the subscription was used—reducing unjustified refunds and protecting your earnings.

## How it works

1. A user requests a refund through the App Store.
2. Apple sends a notification asking for transaction and usage details.
3. If no response is provided, Apple will likely approve the refund by default.
4. **Refund Keeper** automatically processes these requests and submits the necessary app usage data to Apple.
5. With better insights, **Apple is less likely to approve unjustified refunds**, keeping more revenue in your hands.

<img alt="" />

***

## Requirements to Use Refund Keeper

Before enabling Refund Keeper, make sure you’ve completed these steps:

1. **You implemented Qonversion in [Analytics](analytics-mode) or [Subscription Management](subscription-management-mode) Mode** We can only send required app usage data linked to transactions to Apple if we are aware of these transactions.

2. **Qonversion Growth Plan** Refund Keeper is available exclusively on the **Qonversion Growth Plan**. [Upgrade](https://dash.qonversion.io/app/billing) If you haven’t already accessed this feature

3. **Enable Apple Server Notifications V2** Apple send relatable to Refund Keeper events only with second version of notifications. You can switch to v2 in App Store Connect. Read more: [Apple Server-to-Server Notifications (S2S)](ios-s2s-notifications)

4. **Update Your Privacy Policy in App Store Connect** Your Privacy Policy must disclose the collection and sharing of app usage data to comply with Apple's guidelines and ensure transparency for users.

5. **Update Your EULA** To comply with Apple's policies, your app's End User License Agreement (EULA) must include explicit consent for sharing end users' personal data with third parties, including Apple. If you've already integrated the Qonversion SDK, this clause may already be included. Learn more: Learn more:

   * [Apple Developer Guide: Send Consumption Information](https://developer.apple.com/documentation/AppStoreServerAPI/Send-Consumption-Information)
   * [Qonversion Privacy Policy](https://qonversion.io/privacy-policy)

## Refund Preferences

*Apple allows developers to set a refund preference for each request, influencing the decision while Apple retains the final authority.*

| Option             | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| **Always Decline** | Maximizes revenue protection by contesting most refunds.               |
| **Always Refund**  | Automatically approves all refund requests.                            |
| **No Preference**  | A balanced approach that lets Apple decide based on the provided data. |

To adjust this setting, navigate to **Refund Preferences** in the Qonversion Dashboard and select your preferred option.

## Limitations

🚫 **Apple’s App Store Only** – Refund Keeper applies only to **Apple refunds**. Google Play does not support developer-provided usage data for refund evaluations.

⛔ **Not for Consumable Purchases** – Refund Keeper only works for **subscriptions and non-consumable** in-app purchases. Consumable products (e.g., in-game currency) are not eligible.

### Start Protecting Your Revenue Today!

With **Refund Keeper**, you can **reduce refund-related revenue loss and automate refund management with zero extra effort**.

***

[Webhooks](webhooks)

[Enable Refund Keeper](enable-refund-keeper)


# Create Remote Config
Source: https://documentation.qonversion.io/docs/remote-config

Create Remote Configs to manage your onboarding flows, paywall UI, or pricing settings, avoiding extra app releases

The [Remote Config](https://dash.qonversion.io/remote-configs) feature helps you change your onboarding flows, paywall UI, or pricing settings without additional app releases. Moreover, it enables you to rapidly [iterate with your monetization experiments](https://qonversion.io/blog/a-b-paywall-experiments-for-subscription-apps-guide/)

## 1. Select your app context to configure

As a first step, name your remote configuration and select a context (part of your application) you'd like to manage remotely. Examples of app contexts you may configure with us:

* *main\_paywall*: to set up settings for different user segments for your main paywall.
* *main\_paywall\_products*: to manage only products remotely.
* *onboarding*: to set up the entire user onboarding journey.
* *onboarding\_step\_2*: to configure only specific steps of the user onboarding flow.
* *\[your\_key]*: to set up any part of your user's monetization experience.

<Frame>
  <img />
</Frame>

## 2. Add attributes for your configuration

Qonversion Remote Config provides you with flexible in-app values using which **you can set up any behavior and appearance of your app**. The core of these in-app values is a plain JSON file consisting of key-value data. We support the following data types:

* **String**.

  * Use this option to validate pricing, communication, or visual hypothesis.
  * Examples: *native.subs.full.v4.w\.8.99.trial.7d*, *Unlock Fast and Secure Browsing*, *#3076FF*, etc.

* **Number**.

  * Use this option, for example, to show only a subset of your onboarding screens.
  * Examples: *2*, *5*, *23*, etc.

* **Boolean**.

  * Use this option to turn on or off some features.
  * Examples: *true*, *false*

* **Json**.

  * Use this option to validate advanced changes in your app's behavior.
  * Examples: `{"banner_text": "Choose your plan", "product_top": "native.subs.full.v4.w.8.99.trial.7d", "product_bottom": "subs.month.17.99", "skip_onboarding": true}`.

<Frame>
  <img />
</Frame>

## 3. Integrate changes into your app

<Info>
  ### Configuration source

  Qonversion Remote Configs and Experiments share single methods to get configurations. You can distinguish the source of the result received by looking at the *source* field. [Learn more about fields available](remote-config#remoteconfig-fields-description).
</Info>

To receive the configuration **with the Context key set**, call the following Qonversion `remoteConfig` method.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig(contextKey: "my_context_key") { remoteConfig, error in
      // Use remoteConfig here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfig:@"my_context_key" completion:^(QONRemoteConfig * _Nullable remoteConfig, NSError * _Nullable error) {
      // Use remoteConfig here
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig("my_context_key", object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          // Use remoteConfig here
      }

      override fun onError(error: QonversionError) {
          // Handle error here
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfig("my_context_key", new QonversionRemoteConfigCallback() {
      @Override
      public void onSuccess(@NonNull QRemoteConfig remoteConfig) {
          // Use remoteConfig here
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // Handle error here
      }
  });
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: "my_context_key");
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig("my_context_key", (remoteConfig, error) =>
  {
      // Use remoteConfig here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');
  ```

  ```typescript Capacitor theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');
  ```
</CodeGroup>

In case you're using configurations with **empty Context key**, call the same method with no arguments added:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfig { remoteConfig, error in
      // Use remoteConfig here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfig:^(QONRemoteConfig * _Nullable remoteConfig, NSError * _Nullable error) {
      // Use remoteConfig here
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfig(object : QonversionRemoteConfigCallback {
      override fun onSuccess(remoteConfig: QRemoteConfig) {
          // Use remoteConfig here
      }

      override fun onError(error: QonversionError) {
          // Handle error here
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfig(new QonversionRemoteConfigCallback() {
      @Override
      public void onSuccess(@NonNull QRemoteConfig remoteConfig) {
          // Use remoteConfig here
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // Handle error here
      }
  });
  ```

  ```typescript React Native theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```

  ```dart Flutter theme={null}
  final remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfig((remoteConfig, error) =>
  {
      // Use remoteConfig here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```

  ```typescript Capacitor theme={null}
  const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();
  ```
</CodeGroup>

If necessary, you can also request a list of remote configs for all the context keys, including the empty one.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfigList { remoteConfigList, error in
    // Use remoteConfigList here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfigList:^(QONRemoteConfigList * _Nullable remoteConfigList, NSError * _Nullable error) {
    // Use remoteConfigList here
  }]
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfigList(object : QonversionRemoteConfigListCallback {
      override fun onSuccess(remoteConfigList: QRemoteConfigList) {
          // Use remoteConfigList here
      }

      override fun onError(error: QonversionError) {
          // Handle error here
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfigList(new QonversionRemoteConfigListCallback() {
      @Override
      public void onSuccess(@NonNull QRemoteConfigList remoteConfigList) {
        // Use remoteConfigList here
      }

      @Override
      public void onError(@NonNull QonversionError error) {
        // Handle error here
      }
  });
  ```

  ```typescript React Native theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```

  ```dart Flutter theme={null}
  final remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfigList((remoteConfigList, error) =>
  {
      // Use remoteConfigList here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```

  ```typescript Capacitor theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();
  ```
</CodeGroup>

If you need remote configs for a specific set of context keys, just use the following method.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().remoteConfigList(
    contextKeys: ["my_context_key", "another_context_key"],
    includeEmptyContextKey: true // to include remote config without context key
  ) { remoteConfigList, error in
    // Use remoteConfigList here
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] remoteConfigList:@[@"my_context_key", @"another_context_key"]
                         includeEmptyContextKey:YES // to include remote config without context key
   																	 completion:^(QONRemoteConfigList * _Nullable remoteConfigList, NSError * _Nullable error) {
    // Use remoteConfigList here
  }
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.remoteConfigList(
      listOf("my_context_key", "another_context_key"),
      true, // to include remote config without context key
      object : QonversionRemoteConfigListCallback {
          override fun onSuccess(remoteConfigList: QRemoteConfigList) {
              // Use remoteConfigList here
          }

          override fun onError(error: QonversionError) {
              // Handle error here
          }
  	  }
  )
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().remoteConfigList(
      Arrays.asList("my_context_key", "another_context_key"),
      true, // to include remote config without context key
      new QonversionRemoteConfigListCallback() {
          @Override
          public void onSuccess(@NonNull QRemoteConfigList remoteConfigList) {
              // Use remoteConfigList here
          }

          @Override
          public void onError(@NonNull QonversionError error) {
              // Handle error here
          }
  		}
  );
  ```

  ```typescript React Native theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ['my_context_key', 'another_context_key'],
    true // to include remote config without context key
  );
  ```

  ```dart Flutter theme={null}
  final remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ["my_context_key", "another_context_key"],
    true // to include remote config without context key
  );
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().RemoteConfigList(
    new string[] {"my_context_key", "another_context_key"},
    true, // to include remote config without context key
    (remoteConfigList, error) =>
  {
      // Use remoteConfigList here
  });
  ```

  ```typescript Cordova theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ['my_context_key', 'another_context_key'],
    true // to include remote config without context key
  );
  ```

  ```typescript Capacitor theme={null}
  const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
    ['my_context_key', 'another_context_key'],
    true // to include remote config without context key
  );
  ```
</CodeGroup>

### `RemoteConfigList` fields description

| Field                          | Description                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| remoteConfigs                  | The list of requested remote configs                                                  |
| remoteConfigForContextKey      | Function for requesting specific remote config from the above list by the context key |
| remoteConfigForEmptyContextKey | Function for requesting the remote config from the above list with empy context key   |

### `RemoteConfig` fields description

| Field      | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| payload    | JSON payload you have configured using the Qonversion dashboard. |
| experiment | Object (`Experiment`) with the experiment's information.         |
| source     | Source (`RemoteConfigurationSource`) of the configuration.       |

### `Experiment` description

| Field         | Description                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------- |
| identifier/id | Experiment's identifier.                                                                      |
| name          | Experiment's name. The same as you set in Qonversion. You can use it for analytical purposes. |
| group         | Experiment's group (`ExperimentGroup`) the user has been assigned to.                         |

### `ExperimentGroup` description

| Field         | Description                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------- |
| identifier/id | Experiment group's identifier.                                                                      |
| name          | Experiment group's name. The same as you set in Qonversion. You can use it for analytical purposes. |
| type          | Type of the experiment's group. Either control or treatment.                                        |

### `RemoteConfigurationSource` description

| Field          | Description                                                                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| identifier/id  | Either experiment's or remote config's ID.                                                                                                                                                                                                                                            |
| name           | Either experiment's or remote config's name.                                                                                                                                                                                                                                          |
| assignmentType | How the current payload was assigned: `automatic` (sticky, re-evaluated on targeting changes) or `manual` (overrides targeting, never re-evaluated until detach/archive/delete — including pins created by [Freeze assignments](/docs/remote-config-targeting#freezing-assignments)). |
| type           | One of the following: *experiment control group*, *experiment treatment group*, *remote configuration*.                                                                                                                                                                               |
| contextKey     | Context key assigned to either experiment or remote config.                                                                                                                                                                                                                           |

Please, note:

* If you're using the [Qonversion Experiments](https://dash.qonversion.io/ab-testing) feature, the `remoteConfig`object will also contain experiment-related fields.
* Qonversion assigns eligible users to launched experiments once the `remoteConfig` is called. We also recommend paying attention to the [Segmentation rules](remote-config#5-segment-users) for the configuration. For how assignments, caching, and re-evaluation interact, see [How targeting and assignment works](/docs/remote-config-targeting).

### Invalidate the config cache

Responses are cached in memory per context key, so a `remoteConfig` call may serve a cached copy without a network call. Call `invalidateRemoteConfigsCache` when the targeting inputs changed and you need the change reflected immediately — for example, after setting a batch of user properties your targeting depends on. The method performs no network request itself; it marks the cached values as stale, so the next `remoteConfig` / `remoteConfigList` call fetches a fresh evaluation from the server.

You do **not** need to call it after `identify` — the SDK drops the config cache on identity changes automatically. Call it after SDK initialization: calling earlier throws on Android and is a no-op on iOS. For the full caching rules, see [When a device fetches a config](/docs/remote-config-targeting#when-a-device-fetches-a-config).

Available since: iOS 6.14.0, Android 9.7.0, React Native 10.11.0, Flutter 11.10.0, Cordova 7.9.0, Capacitor 1.8.0, Unity 9.9.0.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().invalidateRemoteConfigsCache()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] invalidateRemoteConfigsCache];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.invalidateRemoteConfigsCache()
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().invalidateRemoteConfigsCache();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().invalidateRemoteConfigsCache();
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().invalidateRemoteConfigsCache();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().InvalidateRemoteConfigsCache();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().invalidateRemoteConfigsCache();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().invalidateRemoteConfigsCache();
  ```
</CodeGroup>

## 4. Test changes before launch

<Info>
  Please, note, the guide below allows you to test only configurations created through the [Remote Config dashboard section](https://dash.qonversion.io/remote-configs). To test configurations from the [Experiments section](https://dash.qonversion.io/ab-testing), please, follow the [test experimental changes before launch](launch-experiments#test-experimental-changes-before-launch) guide.
</Info>

We highly recommend testing if your app works properly with the changes you want to roll out to your users. You can do so by following the following steps:

1. Copy the ID for your remote config

<Frame>
  <img />
</Frame>

2. Pass the values to Qonversion SDK by using the `attachUserToRemoteConfiguration` method

This creates a **manual assignment**: it overrides targeting rules and is never re-evaluated — the pin survives config edits until you detach the user, or archive/delete the configuration (see [Assignments: why evaluation is sticky](/docs/remote-config-targeting#assignments-why-evaluation-is-sticky)). Attaching or detaching also drops the SDK's in-memory config cache, so the next fetch reflects the change immediately.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().attachUser(toRemoteConfiguration: "your_remote_configuration_id") { success, error in
       // handle result
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] attachUserToRemoteConfiguration:@"your_remote_configuration_id" completion:^(BOOL success, NSError * _Nullable error) {
      // handle result
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.attachUserToRemoteConfiguration("your_remote_configuration_id", object : QonversionRemoteConfigurationAttachCallback {
      override fun onSuccess() {
          // handle success
      }

      override fun onError(error: QonversionError) {
          // handle error
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id", new QonversionRemoteConfigurationAttachCallback() {
      @Override
      public void onSuccess() {
          // handle success
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error
      }
  });
  ```

  ```typescript React Native theme={null}
  await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");
  ```

  ```dart Flutter theme={null}
  await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().AttachUserToRemoteConfiguration("your_remote_configuration_id", (success, error) =>
  {
      // handle result
  });
  ```

  ```typescript Cordova theme={null}
  await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");
  ```

  ```typescript Capacitor theme={null}
  await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");
  ```
</CodeGroup>

* In case your user has already been attached to another configuration, use the `detachUserFromRemoteConfiguration` method.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().detachUser(fromRemoteConfiguration: "attached_remote_configuration_id") { success, error in
      // handle result
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] detachUserFromRemoteConfiguration:@"attached_remote_configuration_id" completion:^(BOOL success, NSError * _Nullable error) {
      // handle result
  }];
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.detachUserFromRemoteConfiguration("attached_remote_configuration_id", object : QonversionRemoteConfigurationAttachCallback {
      override fun onSuccess() {
          // handle success
      }

      override fun onError(error: QonversionError) {
          // handle error
      }
  })
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id", new QonversionRemoteConfigurationAttachCallback() {
      @Override
      public void onSuccess() {
          // handle success
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error
      }
  });
  ```

  ```typescript React Native theme={null}
  await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");
  ```

  ```dart Flutter theme={null}
  await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().DetachUserFromRemoteConfiguration("attached_remote_configuration_id", (success, error) =>
  {
      // handle result
  });
  ```

  ```typescript Cordova theme={null}
  await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");
  ```

  ```typescript Capacitor theme={null}
  await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");
  ```
</CodeGroup>

3. Call the Qonversion `remoteConfig` method. Now Qonversion SDK returns data associated with previously set remote config.
4. Validate your app logic without launching the configuration.

<Warning>
  ### Pay attention before release

  Do not forget to remove the usage of the `attachUserToRemoteConfiguration` method before your app release. Otherwise, all your users may be exposed to only one remote config.
</Warning>

## 5. Segment users

Qonversion Remote Config has flexible options to target a desired user segment.

Segment users by:

* **App install date**
  * Use this option to assign the configuration only to new app installs.
* **App version**
  * Use this option to assign the configuration only for users with the app version with the new features implemented. This is your app's **version name**, not its build number — `versionName` on Android (never `versionCode`) and `CFBundleShortVersionString` on iOS (never `CFBundleVersion`). See [Matching on app version](#matching-on-app-version) below.
* **Country**
  * Use this option to run new behavior only in selected countries.
* **Store**
  * Use this option to target only a specific store (Apple App Store or Google Play).
* **User's active subscription**
  * Use this option to target only users with/without any active subscriptions or having a specific one.
* **Purchased product**
  * Use this option to target users based on their purchase history. You can select specific products or use `(any)` to match users who made at least one purchase, or `(none)` for users with no purchase history. Unlike "Active subscription", this filter checks all purchases regardless of their current status (active, expired, or cancelled).
* **Last purchase date**
  * Use this option to target users based on when they made their most recent purchase. For example, you can target users whose last purchase was more than 60 days ago to identify churned users.

<Frame>
  <img />
</Frame>

Targeting rules combine with a deterministic rollout percentage and sticky assignments: a user who receives the config keeps it, rule edits re-evaluate only automatic assignments (rolling out project by project), and manual pins are never re-evaluated. For the full evaluation model, see [How targeting and assignment works](/docs/remote-config-targeting).

### Matching on app version

The SDK reports the **version name** your app displays to users — `versionName` on Android, `CFBundleShortVersionString` on iOS — and the App version rule compares your value against that. The Android `versionCode` and the iOS `CFBundleVersion` build numbers are never sent to Qonversion, so they cannot be targeted directly. If you need to segment by build number, set it as a [user property](user-properties) and target it with a **User properties** rule instead.

The ordering comparators (*is greater than*, *is less than*, *is in range*) compare both sides as [semantic versions](https://semver.org), so `1.10.0` is correctly greater than `1.9.0`. Two cases are worth watching for, because neither reports an error — the rule simply targets the wrong set of users:

* **A build number used as the value.** A bare number such as `24` passes the input validation, but it is then compared against version names like `1.8.4` — so *is greater than* matches nobody, and *is less than* matches everybody.
* **A version name that is not semver-shaped.** If your app reports something like `2.0.9_08042026`, it cannot be parsed as a version, and every ordering comparator matches nobody.

If your version name does not follow the `MAJOR.MINOR.PATCH` format, use *is one of* / *is none of* instead — they compare the string exactly and work with any format.

## 6. Launch the configuration

Once you have added all the necessary properties to your in-app configuration, validated changes in your app, and assigned desired segmentation rules, the only thing left is to click the Create button to move the configuration from Draft to Active state. Active configs are fetched lazily — nothing is downloaded until your code requests a config; see [When a device fetches a config](/docs/remote-config-targeting#when-a-device-fetches-a-config).

<Frame>
  <img />
</Frame>

## 7. Fallback files (optional)

To enhance the reliability of remote configurations, consider utilizing Qonversion [fallback files](system-reliability#fallback-files). These files will serve as a backup in case of network provider errors or system failures, ensuring that your application continues to receive essential data and avoids any downtime. For more information on fallback files and how to install them, please refer to [this page](system-reliability#fallback-files).

***

What’s Next

* [How targeting and assignment works](remote-config-targeting)
* [Launch A/B test from Remote Config](launch-test-from-remote-config)


# How targeting and assignment works
Source: https://documentation.qonversion.io/docs/remote-config-targeting

The mechanics behind who gets which Remote Config: first-match by priority, deterministic rollout, sticky assignments, re-evaluation, and how user properties and identify interact with targeting

This page describes the evaluation model behind [Remote Configs](/docs/remote-config) — what happens on the device and on the server when your app asks for a config, and what changing targeting rules does to users who already received one.

## When a device fetches a config

Remote configs are fetched **lazily**: nothing is loaded at app start. The SDK requests configs when your code calls `remoteConfig()` / `remoteConfigList()` (or their equivalents on wrapper SDKs).

Two things to know about the fetch:

1. **Pending user properties are flushed first.** Before every remote config request the SDK force-sends any user properties waiting in its debounce queue and only then calls the config endpoint — so a config requested right after `setUserProperty(...)` is evaluated with that property already stored. The server reads properties synchronously at request time; there is no replication lag.
2. **Responses are cached in memory** per context key for the lifetime of the process. A cached config is served without a network call. The cache is dropped when:
   * the user changes (identify with a different user id, logout) — and on iOS 6.14.0+, Android 9.7.0+, and the wrapper versions listed below, on **any** `identify` call, even with the same id;
   * you call `attachUserToRemoteConfiguration` / `detachUserFromRemoteConfiguration` (or the experiment counterparts) — **all** cached configs are invalidated, including named context keys;
   * you call `invalidateRemoteConfigsCache()` explicitly (iOS 6.14.0+, Android 9.7.0+, React Native 10.11.0+, Flutter 11.10.0+, Cordova 7.9.0+, Capacitor 1.8.0+, Unity 9.9.0+).

If the network request fails, the SDK can serve a [bundled fallback file](/docs/remote-config#7-fallback-files-optional). Fallbacks are never cached — the next call retries the network.

## How one config is chosen among several

When several configurations share a context key, the server picks at most one:

1. **Experiments win first.** If the user is assigned to a group of a non-finished experiment for that context key, the experiment's payload is returned. Finished experiments release their users.
2. **Remote configurations are evaluated in priority order** — the order you set on the Remote Configs list (drag-and-drop in the dashboard). The **first** configuration whose targeting matches the user wins; users who don't match fall through to the next one.
3. For each candidate the server checks **targeting rules** (`segmentation_conditions`, including audience references) and then the **rollout percentage** (`segment_percent`).

The rollout percentage is **deterministic**: each user is bucketed by a stable hash of the configuration and their user id into 0–99 and admitted when the bucket is below the percent. Consequences:

* The same user gets the same in/out decision on every evaluation — a config edit never reshuffles who is inside the rollout.
* **Raising the percent only adds users** (the newly admitted top buckets); lowering it removes only the users in the topmost buckets.

If nothing matches, the SDK gets no config for that context key.

## Assignments: why evaluation is sticky

The first evaluation that matches a configuration is **persisted** as an assignment (attachment) for that user and context key. Later requests serve the stored assignment directly — the targeting rules are not re-run on every request. This is what makes delivery cheap and consistent: a user who saw a price or a paywall keeps seeing it.

There are two assignment types, reported in the SDK's `RemoteConfigurationSource.assignmentType`:

* **Automatic** — assigned by matching targeting rules.
* **Manual** — pinned explicitly via `POST /remote-configurations/{config_id}/users/{user_id}` or the SDK attach methods. A manual pin **overrides targeting rules and is never re-evaluated** — it survives config edits until you detach it, archive the config, or delete it.

## Freezing assignments

A configuration can be **frozen** with the *Freeze assignments* switch in the dashboard's Targeting card. While frozen, every user who **newly** receives the configuration is stored as a **manual pin** instead of an automatic assignment — so later targeting, rollout, or priority changes never re-seat them (nothing in the re-evaluation list below applies to manual pins).

* **Enabling freeze** offers a one-shot option to also pin the users who already received the configuration automatically. Skip it, and only future recipients are pinned — existing automatic assignments stay re-evaluable.
* **Disabling freeze is one-way**: pins created while it was on stay pinned (they are indistinguishable from pins you made yourself). Only new deliveries become re-evaluable again.
* **Payload edits still apply** to pinned users — freezing controls *who* keeps the config, not *what* they receive.
* To release pinned users, detach them individually or archive/delete the configuration.

Freeze-made pins report `assignmentType: manual`, exactly like your own pins.

## What re-evaluates an automatic assignment

Automatic assignments are re-evaluated when the targeting they were computed against changes. Any of these bumps the configuration's targeting epoch:

* editing the configuration's targeting rules or `segment_percent`;
* publishing or restoring a configuration version;
* reordering priorities within the context key;
* editing an **audience** referenced by the configuration's rules — this re-evaluates every configuration that references it.

On the user's **next request** after such a change, the server evaluates them against the current rules:

* still matching → they keep the configuration (nothing changes);
* no longer matching → they migrate to the next matching configuration in priority order, or to none.

<Note>
  **Gradual rollout.** Re-evaluation is being enabled project by project. On projects not yet migrated, automatic assignments are **never** re-evaluated: targeting edits apply only to users who have no assignment yet (new users, or after a manual detach). Manual pins behave the same on every project. Contact support if you want your project migrated.
</Note>

Two changes apply **without** any re-evaluation:

* **Payload edits are live.** The payload is read fresh on every request, so attached users see new values on their next fetch regardless of re-evaluation.
* **Archiving or deleting a configuration** releases everyone attached to it immediately.

## Changing experiment traffic mid-flight

Experiment assignments are persisted per user — **including rejections** — which makes experiment traffic changes asymmetric with remote-config rollouts:

* **Raising the traffic allocation** admits only users the experiment has never evaluated. A user previously rejected by the traffic gate was excluded persistently and is **not** re-admitted — the monotonic-ramp property of remote-config rollouts does not extend to experiments.
* **Lowering the traffic allocation** evicts no one: users already assigned keep their group; the new percent gates only first-time evaluations.
* **Changing the group split** (e.g. 50/50 → 70/30) never migrates existing assignments — group membership is drawn at admission and stored. The new weights apply to newly admitted users only.
* **Finishing the experiment** is the only change that releases everyone at once.

## User properties in targeting

User properties set via the SDK participate in targeting rules (`user_properties` conditions) and in audience definitions:

* Properties are batched on the device with a \~5 second debounce, then sent in one request. Backgrounding the app flushes them immediately.
* As covered above, the SDK flushes pending properties **before** every remote config fetch and waits for that flush — the "property race" does not exist on the config path: what you set is what the evaluation sees.
* If a flush fails, the SDK retries with backoff; a cached config served from memory still triggers the flush, so properties are not swallowed by a cache hit.

## Identify and assignments

What happens on `identify(...)` depends on whether the user id changes:

* **First login (identity created for the current user):** the id stays the same. On iOS 6.14.0+, Android 9.7.0+, React Native 10.11.0+, Flutter 11.10.0+, Cordova 7.9.0+, Capacitor 1.8.0+, and Unity 9.9.0+, `identify` drops the config cache **even when the id doesn't change** — the next fetch evaluates fresh against that user's stored assignments and properties. On older SDK versions nothing is re-evaluated by itself: call `invalidateRemoteConfigsCache()` or simply wait for the next cold start.
* **Returning user / second device (identity already exists):** the SDK switches to the existing user id, drops the config cache, and the next fetch evaluates fresh — against the assignments and properties of *that* user. Anonymous-user assignments do not transfer to the identified user.
* **Logout:** the SDK reverts to the original anonymous user of this device (the one active before the first `identify` — no new user is created); the cache is dropped.
* **Repeat `identify` with the already-attached identity:** a no-op on the SDK side — no network call, no cache drop. To force a re-evaluation in that state, call `invalidateRemoteConfigsCache()`.

## Summary

| Question                                                  | Answer                                                                                                                  |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Which config wins among several?                          | Experiment group first; otherwise the first priority-ordered configuration whose rules + rollout match                  |
| Is the rollout random per request?                        | No — deterministic per user; edits never reshuffle membership                                                           |
| Does a user keep their config?                            | Yes — assignments are persisted; payload edits still apply live                                                         |
| When are users re-evaluated?                              | On their next request after a targeting/rules/version/priority/audience change (per-project rollout; manual pins never) |
| What makes assignments immune to re-evaluation?           | Freezing the configuration — new recipients are stored as manual pins; disabling freeze keeps existing pins             |
| Does raising experiment traffic re-admit rejected users?  | No — experiment rejections are persisted; only never-evaluated users are admitted                                       |
| Do user properties apply to the very next config request? | Yes — the SDK force-flushes them before every fetch                                                                     |
| What detaches everyone at once?                           | Archiving or deleting the configuration; finishing an experiment releases its users                                     |


# Revenue
Source: https://documentation.qonversion.io/docs/revenue

Analyze subscription revenue metrics including sales, proceeds, refunds, ARPU, MRR, and ARR in the Qonversion Revenue dashboard.

## Available Charts

### Sales

Available data: revenue after refunds, refunds. All metrics are before deducting the App Stores' commission.

<Frame>
  <img />
</Frame>

### Proceeds

Available data: net revenue (after refunds), refunds. All metrics are after deducting the App Stores' commission.

<Frame>
  <img />
</Frame>

### Refunds

Quickly analyse your refunds by product, country, or any other segment.

<Frame>
  <img />
</Frame>

### Refund Rate

The Refund Rate chart shows refunded purchases as a share of all purchases for the selected period. Use it to spot quality, billing, or fraud issues by segment.

The chart's title shows the Refund Rate for the selected period; the percentage shows how this value changed compared to the previous period of the same length. Filter or group by product, country, currency, or any other supported attribute to find where refunds concentrate.

Available at `https://dash.qonversion.io/analytics/revenue/refund-rate`.

### ARPU

The Average Revenue Per User (ARPU) chart shows total revenue divided by the number of users for the selected period. ARPU is a top-line monetisation metric that captures both conversion and pricing.

The chart's title shows ARPU for the selected period; the percentage shows how this value changed compared to the previous period of the same length. ARPU is reported with two-decimal precision.

Available at `https://dash.qonversion.io/analytics/revenue/arpu`.

### ARPPU

The Average Revenue Per Paying User (ARPPU) chart shows total revenue divided by the number of paying users for the selected period. Unlike ARPU, ARPPU isolates the spend behaviour of users who actually pay and is the better signal for pricing or paywall changes.

The chart's title shows ARPPU for the selected period; the percentage shows how this value changed compared to the previous period of the same length. ARPPU is reported with two-decimal precision.

Available at `https://dash.qonversion.io/analytics/revenue/arppu`.

### MRR

The Monthly Recurring Revenue (MRR) chart shows the normalized monthly revenue from all active subscriptions for the selected dates. The MRR chart includes only subscriptions with auto-renewal turned on. For normalizing subscriptions' prices to a month, we use the following multiples depending on a subscription duration:

* Weekly subscription multiple: 4.35,
* Monthly subscription multiple: 1.0,
* Two months subscription multiple: 0.5,
* Three months subscription multiple: 0.33,
* Six months subscription multiple: 0.166,
* Annual subscriptions multiple: 0.083.

The chart's title shows your MRR at the end of the selected period. The percentage reflects the change in monthly recurring revenue during the selected period. In the example below, MRR equals \$120,711 on the 31st of May. That is 68.58% higher than on the 1st of May.

<Frame>
  <img />
</Frame>

### MRR Movement

MRR Movement helps you understand how subscriber base changes affect your monthly recurring revenue over time. This chart shows the revenue change caused by new paid subscriptions (above zero), and churned or cancelled subscriptions (below zero), i.e., expired, refunded or cancelled subscriptions.

The chart's title shows the net recurring revenue during the selected period; the percentage shows how this value changed compared to the previous period of the same length. In the example below, the MRR increased by \$48,106, which is 61.88% higher than the growth in the previous period of the same length (31 days).

<Info>
  ### Billing Grace Period and MRR/ARR

  When a subscription enters billing retry, app stores may grant a **billing grace period** during which the subscriber retains access while the store attempts to recover payment. Qonversion uses the store-configured grace period duration to determine how subscriptions in billing retry are reflected in MRR, ARR, MRR Movement, and ARR Movement charts:

  * **Grace period configured**: the subscription continues to count toward MRR/ARR during the grace period. It is counted as churned in MRR/ARR Movement only after the grace period expires, not at the moment billing retry begins.
  * **No grace period**: the subscription stops contributing to MRR/ARR at the end of the last paid period.

  Qonversion reads the grace period configuration from App Store Connect (for Apple) and from the base plan settings in Google Play Console (for Google). If you change your grace period settings in the store, it will be reflected in MRR/ARR calculations for new billing retry events.
</Info>

<Frame>
  <img />
</Frame>

### ARR

The Annual Recurring Revenue (ARR) chart shows the normalized annual revenue from all active subscriptions for the selected dates. It works the same way as [MRR](revenue#mrr) above, except that the revenue is normalized by 12 months.

<Frame>
  <img />
</Frame>

### ARR Movement

The Annual Recurring Revenue Movement chart works the same way as [MRR Movement](revenue#mrr-movement), except that the revenue is normalized by 12 months.

<Frame>
  <img />
</Frame>

***

[Monitoring](monitoring)

[New users](users)


# Sample Apps
Source: https://documentation.qonversion.io/docs/sample-apps

Explore iOS and Android sample applications demonstrating Qonversion Subscription Management mode and AppsFlyer integration.

[iOS](https://github.com/qonversion/qonversion-ios-sdk/tree/main/Sample) and [Android](https://github.com/qonversion/android-sdk/tree/develop/app/src/main/java/com/qonversion/android/app) sample apps demonstrating:

* In-app subscriptions implementation with [Qonversion Subscription Management mode](subscription-management-mode)
* AppsFlyer integration

[Flutter](https://github.com/qonversion/flutter-sdk/tree/master/example) sample app | [React Native](https://github.com/qonversion/react-native-sdk/tree/main/example) sample app | [Cordova](https://github.com/qonversion/cordova-plugin/tree/main/sample) sample app | [Capacitor](https://github.com/qonversion/capacitor-plugin/tree/main/example) sample app

***

[Upgrade and Downgrade in Google](google-upgrade-downgrade-or-change-subscription)

[Tutorials](tutorials)


# Scheduled Reports
Source: https://documentation.qonversion.io/docs/scheduled-reports

Automate recurring raw-data export of subscription events to cloud storage, email, Slack, or webhooks on a schedule.

Scheduled reports allow you to automate [raw data export](raw-data-reports). It is helpful to:

* automatically receive raw data for enriching your data infrastructure with subscription events;
* deliver reports to your team on a schedule.

## Configure a Scheduled Report

Select [Scheduled Reports](https://dash.qonversion.io/scheduled-reports) from the menu in your Qonversion account.

<Frame>
  <img />
</Frame>

Provide the following details to set up your report:

* Report Name – an internal report name for your reference, e.g., "Morning analytics reports";
* Send At – a time when the report will be prepared and sent, 30-minute time intervals available;
* Destination – destination where your report will be sent. The following options are available: Google Cloud Storage, Amazon S3, Webhook, Email, Slack.
* Included Range – report period: 1, 3, or 7 days based on the date on which our system receives the event
* Status – draft or active.

Events of what period we will send

* From (Send At - Included Range) to (Send At).

* Example:

  * you set up: Send At: 02:00 UTC, Included range: 3 days
  * on Feb 15 shortly after 02:00 we send you events from Feb 12 02:00 to Feb 15 02:00

<Info>
  Please note that subscription events in Scheduled Reports are being sorted by event receive date (i.e. the date when Qonversion detected the event)
</Info>

## Destinations

### Google Cloud Storage

1. Create a Google Cloud Storage destination accordingly to the [integration guide](google-cloud-storage)
2. Navigate to the [Scheduled Reports tab](https://dash.qonversion.io/scheduled-reports) and click the **Create** button.
3. Fill in all the required fields, select **Google Cloud Storage** as the destination, and then click the **Create** button again.
4. After the configuration is created, we will be sending Raw Data reports with the following file name structure:
   * `[YYYY_MM_DD]_[report_name]_[project_name]_[platform]_[uid_in_qonversion].<ext>` (extension depends on the underlying file format - typically `.gzip`)

### Amazon S3

1. Create an Amazon S3 destination accordingly to the [integration guide](amazon-s3)
2. Navigate to the [Scheduled Reports tab](https://dash.qonversion.io/scheduled-reports) and click the **Create** button.
3. Fill in all the required fields, select **Amazon S3** as the destination, and then click the **Create** button again.
4. After the configuration is created, we will be sending Raw Data reports with the following file name structure:
   * `[YYYY_MM_DD]_[report_name]_[project_name]_[platform]_[uid_in_qonversion].<ext>` (extension depends on the underlying file format - typically `.gzip`)

### Webhook

1. Create a Webhook destination accordingly to the [Webhook integration guide](webhooks). You can optionally provide a header token in the integration settings - it will be sent as a `Bearer` authorization header on each delivery.
2. Navigate to the [Scheduled Reports tab](https://dash.qonversion.io/scheduled-reports) and click the **Create** button.
3. Fill in all the required fields, select *Webhooks* as the destination, and then click the **Create** button again.

<Check>
  ### Done

  Now your scheduled reports can be sent to your Webhook destination. Don't forget to set it as **Active** to activate it.
</Check>

POST request to webhook destination with payload:

<CodeGroup>
  ```json theme={null}
  {
     "report_uid": "4AJ-qk3",
     "report_name": "Morning Report",
     "project_key": "project_key",
     "platform": "iOS",
     "delete_at": 1604236720,
     "link": "link",
     "send_at": 37800,
     "period": 86400,
     "environment": 1
  }
  ```
</CodeGroup>

| Field        | Description                                             |
| ------------ | ------------------------------------------------------- |
| report\_uid  | Unique report ID                                        |
| report\_name | Report name                                             |
| project\_key | Your Qonversion [project key](getting-started)          |
| platform     | iOS or Android                                          |
| delete\_at   | Timestamp when a report will be deleted from our server |
| link         | Link to your CSV report file                            |
| send\_at     | Time of a report in seconds from a day start            |
| period       | Period of the report                                    |
| environment  | 1 - production, 0 - sandbox;                            |

### Email

1. Navigate to the [Scheduled Reports tab](https://dash.qonversion.io/scheduled-reports) and click the **Create** button.
2. Fill in all the required fields, select **Email** as the destination, and pick the recipient(s) from the project members list. Click the **Create** button again.
3. Recipients will receive each scheduled report at the configured time.

### Slack

1. Create a Slack destination accordingly to the [Slack integration guide](slack)
2. Navigate to the [Scheduled Reports tab](https://dash.qonversion.io/scheduled-reports) and click the **Create** button.
3. Fill in all the required fields, select Slack as the destination, and then click the **Create** button again.

<img alt="" />

***

[Raw Data Export](raw-data-reports)

[Custom Proxy Server](custom-proxy-server-for-sdks)


# Screens Preloading
Source: https://documentation.qonversion.io/docs/screens-preloading

When showcasing your No-Code screens with Qonversion, there is typically a delay as the content is fetched from our API. This latency can impact user experience, making it crucial to minimize the time it takes for screens to become visible. To address this challenge, we offer a screen preloading feature through our SDK.

This functionality allows you to preemptively load the necessary screens before they are displayed to the user. By leveraging this capability, you can ensure that your No-Code screens are ready for instant display, significantly improving performance and user engagement. With preloaded screens, your application can provide a seamless experience, as users will not have to wait for content to be retrieved during interaction.

In the No-Codes Builder, you can choose to mark the screen as preloadable. Simply navigate to Settings -> General, enable the specified option, and then save your changes.

<img alt="" />

With this setup, your screen will be fully loaded following the SDK initialization and will be prepared by the time you're ready to display it. That's truly all that's required. No coding necessary!

Please note that we impose a limit of 20 preloadable screens per project to avoid excessive network load on users.

<Info>
  If you want to check a screen's availability at runtime and load it on demand before presenting it — for example, to show your own fallback UI when the screen is unavailable — see [Loading screens before presentation](displaying-no-codes#loading-screens-before-presentation).
</Info>

### Supported SDK versions

| Platform         | SDK Version     |
| ---------------- | --------------- |
| iOS              | 6.0.0+          |
| Android          | No-Codes 1.0.0+ |
| React Native     | 10.0.0+         |
| Flutter SDK      | 11.0.0+         |
| Unity SDK        | 9.0.0+          |
| Cordova Plugin   | 7.0.0+          |
| Capacitor Plugin | 1.0.0+          |

***

[Fallbacks](fallbacks)

[Displaying No-Codes](displaying-no-codes)


# Segment
Source: https://documentation.qonversion.io/docs/segment

Send in-app revenue events to your Segment account

## 1. Set up the SDKs

1. Make sure you have Segment SDK installed. If you do not have Segment integration yet, please use [this documentation](https://segment.com/docs/connections/sources/#mobile).

2. Set Qonversion SDKs following [installing the SDKs](install-sdk) guides.

3. Attribute events sent from Qonversion and events received from the Segment SDK to the same user by setting the same user id to Segment that you set to Qonversion SDK in the [User Identifiers guide](user-identifiers#2-user-id-for-third-party-integrations).

<CodeGroup>
  ```swift Swift theme={null}
  SEGAnalytics.sharedAnalytics().identify("yourSideUserID")
  ```

  ```objectivec Objective-C theme={null}
  [[SEGAnalytics sharedAnalytics] identify:@"yourSideUserID"];
  ```

  ```java Java theme={null}
  Analytics.with(context).identify("yourSideUserID", null, null);
  ```

  ```kotlin Kotlin theme={null}
  Analytics.with(context).identify("yourSideUserID")
  ```
</CodeGroup>

## 2. Configure the Segment Integration

1. Go to your Segment account and copy the [Write Key](https://segment.com/docs/connections/find-writekey/) .

2. Navigate to the Integrations section in your Qonversion project, select [Segment ](https://dash.qonversion.io/app/integration/segment), provide the **Write Key** and Save.

## Event Payload

In case you need details about data sent to Segment, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "userId":"",
     "event":"subscription_renewed",
     "timestamp":1686761639,
     "properties":{
        "product":"product_id",
        "price":2.99,
        "currency":"EUR",
        "storefront":"USA"
     }
  }
  ```
</CodeGroup>

***

[SplitMetrics Acquire](splitmetrics)

[Singular](singular)


# [Sep 2025] Migration guide. React Native 10.
Source: https://documentation.qonversion.io/docs/sep-2025-migration-guide-react-native-10

In this major release of the Qonversion React Native SDK, we've made crucial changes to support No-Codes and The New Architecture along with the React 19+ versions.

## No-Codes support

Qonversion No-Codes are now officially released! For integration steps, please follow our [documentation](no-codes).

## Upgrading library

We've migrated the library to the Qonversion organization in NPM, so along with the version update, you should also change the name of the library and all the imports.

In your *package.json* file, upgrade the name and the version of the Qonversion SDK:

<CodeGroup>
  ```json package.json theme={null}
  // Before
  // "react-native-qonversion": "^9.0.0"

  // Now
  "@qonversion/react-native-sdk": "^10.0.0"
  ```
</CodeGroup>

After upgrading the dependency call `yarn install` to download the library and then upgrade all your imports from the previous version:

<CodeGroup>
  ```javascript theme={null}
  // Before
  // import Qonversion from 'react-native-qonversion'

  // Now
  import Qonversion from '@qonversion/react-native-sdk'
  ```
</CodeGroup>

## Properties renamings

We've made a couple of renamings of our DTO properties to sync them with the rest codestyle. If you were using these fields, simply upgrade their names as described in the table below

| Old name               | New name               |
| ---------------------- | ---------------------- |
| `Product.qonversionID` | `Product.qonversionId` |
| `Product.storeID`      | `Product.storeId`      |
| `Product.basePlanID`   | `Product.basePlanId`   |

***

[\[Nov 2025\] Migration guide. iOS 6.0.0](nov-2025-migration-guide-ios-600)

[\[July 2025\] Migration guide. Google Play Billing Library 8.](july-2025-migration-guide-google-play-billing-library-8)


# Server Notifications
Source: https://documentation.qonversion.io/docs/server-notifications

Server Notifications are notifications sent from supported stores to Qonversion and are configured in the dashboard settings. These notifications contain updates on purchases, cancellations, refunds and conversions so we can ensure we send events promptly.

<Info>
  ### Friendly reminder

  We recommend enabling Server Notifications to speed up [Webhooks](webhooks), third-party Integration events delivery time and Analytics charts update.
</Info>

## Proxy URL

Set proxy URL to receive all incoming Apple App Store or Google Play Notifications on your side, proxying through Qonversion infrastructure. That could be useful if you want to handle Apple's or Google's server-to-server notifications on your server in addition to the Qonversion service.

<img alt="" />

## Paddle webhooks

For [Paddle](paddle-integration), there is nothing to configure manually. When you connect Paddle in **Project Settings → Stores**, Qonversion registers the webhook destination on your Paddle account automatically so that subscriptions, renewals, and refunds flow into Qonversion. See [Paddle Credentials](paddle-credentials) for the connection steps.

***

What’s Next

* [Apple Server-to-Server Notifications](ios-s2s-notifications)
* [Google Developer Notifications](google-developer-notifications)
* [Paddle Integration](paddle-integration)


# Singular
Source: https://documentation.qonversion.io/docs/singular

Send iOS and Android in-app subscription events to Singular with Qonversion

Qonversion sends all [revenue events](integrations-overview#tracked-events), including purchases in your app, trial conversions, renewals and refunds, to your Singular account. This allows you to track your user acquisition performance even without an App open.

## 1. Setup the SDKs

1. Make sure you have Singular SDK installed. You can find more details by following [this link](https://support.singular.net/hc/en-us/categories/360002441132-Singular-SDK-and-S2S).

2. Check whether you [correctly launch Qonversion SDK](user-identifiers#1-qonversion-user-id).

3. For accurate data tracking Qonversion SDK collects platform-related device attributes, such as IDFA, IDFV, ASID, AIFA and ANDI. However, IDFA and ASID are not available by default. At the same time, lack of them can cause a decrease in Singular attribution quality.

   * Learn more about how to [make IDFA available](analytics-mode#5-optional-set-idfa-identifier-for-advertisers-ios-145-only) for Qonversion
   * Learn more about how to [make ASID available](analytics-mode#6-optional-set-asid-app-set-id-android-12-only) for Qonversion

## 2. Configure the Singular Integration

1. Find your Singular *SDK Key: Settings → SDK Keys → SDK Key*

<Frame>
  <img />
</Frame>

2. Navigate to the *Tools → Integrations* section in the [Qonversion Dashboard](https://dash.qonversion.io/)
3. Choose your platform (IOS or Android) and click the *Add new +* button
4. In the Singular Integration setting screen provide the previously gotten SDK Key and your App ID

<Frame>
  <img />
</Frame>

<Warning>
  ### Do not track any purchase events on the client side

  Qonversion tracks all revenue events, so if you track revenue events with Singular SDK, you may double-count the revenue in your Singular account.
</Warning>

<Check>
  ### Done

  Now Qonversion will send In-App purchases and subscription events to your Singular account. At the same time, you can set custom event names on the integration page, turn on proceeds data instead of sales, etc.
</Check>

***

[Segment](segment)

[Slack](slack)


# Slack
Source: https://documentation.qonversion.io/docs/slack

Send Qonversion subscription and in-app purchase events to your Slack workspace through a webhook-based integration.

You can send all valuable subscription and in-app purchase events to your Slack workspace. To enable this integration you need to create an app in Slack.

## 1. Create and Set Up Your Slack App

Please refer to the detailed documentation on creating a Slack App [here](https://slack.com/intl/en-ru/help/articles/115005265063-Incoming-webhooks-for-Slack).

1. Create a new Slack app in the workspace where you want to post messages.
2. From the Features page in Slack, toggle Activate Incoming Webhooks on.
3. Click Add New Webhook to Workspace.
4. Pick a channel that the app will post to, then click Authorize.
5. Copy the created webhook URL

## 2. Configure the Slack Integration

1. Navigate to the Integrations section in your Qonversion project and select Slack.
2. Pass the URL to the Webhook URL field.
3. Choose the events to send and edit the event names if needed.

## Event Payload

In case you need details about data sent to Slack, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
     "channel":"", 
     "username":"",
     "attachments":[
        {
           "fallback":"Subscription Renewed",
           "author_name":"Subscription Renewed",
           "color":"",
           "title":"",
           "title_link":"",
           "footer":"",
           "footer_icon":"",
           "ts":1686432178,
           "fields":[
              {
                 "title":"",
                 "value":"",
                 "short":false
              }
           ]
        }
     ]
  }
  ```
</CodeGroup>

***

[Singular](singular)

[Tenjin](tenjin)


# Social Proof
Source: https://documentation.qonversion.io/docs/social-proof

Social proof templates help build trust and credibility by showcasing customer testimonials, ratings, and reviews. These components are designed to increase conversion by highlighting positive user experiences.

All Social Proof templates support:

* **Customizable star ratings** — including partial fill (e.g., 4.9 stars)
* **Responsive design** — adapts to different screen sizes
* **Full styling control** — colors, fonts, spacing

***

## Carousels

### Reviews Carousel

A horizontal carousel displaying customer reviews with star ratings, testimonial text, and author names. Perfect for showcasing positive feedback and building trust.

<img alt="" />

**Features:**

* 5-star rating display
* Review text with automatic wrapping
* Author name attribution
* External pagination dots
* Autoplay with 3-second default interval
* Centered slides with peek effect

**Use for:**

* Testimonial sections on paywalls
* Customer feedback highlights
* Trust-building before purchase decisions

**Key properties:**

* **Slides Per View** — number of visible slides (default: 1)
* **Space Between** — gap between slides in pixels
* **Autoplay Delay** — seconds between slide transitions
* **Loop** — enable infinite looping
* **Pagination** — show/hide navigation dots

***

### Reviews Carousel 2

An alternative carousel layout with a different visual style. Features the same functionality as Reviews Carousel with varied design treatment.

<img alt="" />

**Features:**

* Star rating with review count
* Full-width review cards
* Author attribution with avatar support
* Smooth slide transitions

***

## Review Blocks

Compact rating displays perfect for headers, hero sections, or anywhere you need a quick trust indicator.

### Review Block 1

Minimal rating display with stars and review count.

<img alt="" />

**Features:**

* 5-star rating display
* Review count text (e.g., "12,456 reviews")
* Compact horizontal layout

**Use for:**

* Header trust badges
* Above-the-fold social proof
* Compact rating indicators

***

### Review Block 2

Rating display with App Store badge styling.

<img alt="" />

**Features:**

* Star rating with score display
* App Store-style presentation
* Source attribution text

**Use for:**

* App Store rating highlights
* Platform-specific social proof
* Trust indicators near CTAs

***

### Review Block 3

Extended block with title, rating, and detailed review count.

<img alt="" />

**Features:**

* Section title ("What users say")
* Large star rating display
* Review count with source
* Expandable layout

**Use for:**

* Dedicated review sections
* Featured testimonial headers
* Detailed rating displays

***

## Review Columns

Vertical lists of customer reviews, ideal for dedicated testimonial sections.

### Review Column 1

Stacked reviews with star ratings in a vertical layout.

<img alt="" />

**Features:**

* Multiple review cards stacked vertically
* Individual star ratings per review
* Review text with author name
* Clean card-based design

**Use for:**

* Testimonial sections
* Review showcases
* Extended social proof areas

***

### Review Column 2

Reviews with avatars, dates, and enhanced visual treatment.

<img alt="" />

**Features:**

* User avatar images
* Review date display
* Star rating per review
* Author name and review text
* Professional card styling

**Use for:**

* Detailed testimonial sections
* User story showcases
* Premium review displays

***

## Review Lines

Inline rating displays for compact spaces and headers.

### Review Line 1

Horizontal compact rating in a single line.

<img alt="" />

**Features:**

* Inline star display
* Rating score (e.g., "4.9")
* Review count
* Minimal footprint

**Use for:**

* Header ratings
* Inline trust indicators
* Space-constrained areas

***

### Review Line 2

Inline rating with source text attribution.

<img alt="" />

**Features:**

* Star rating display
* Rating score
* Source text (e.g., "on App Store")
* Compact single-line layout

**Use for:**

* Platform-attributed ratings
* Source-specific social proof
* Compact header badges

***

## Star Rating Component

<img alt="" />

All review templates use the **Star Rating** custom component, which supports:

| Property        | Description                                   |
| --------------- | --------------------------------------------- |
| **Rating**      | Value from 0-5, supports decimals (e.g., 4.9) |
| **Max Stars**   | Maximum number of stars to display            |
| **Size**        | Star size in pixels                           |
| **Fill Color**  | Color for filled stars                        |
| **Empty Color** | Color for unfilled stars                      |
| **Gap**         | Spacing between stars in pixels               |

**Partial fill support:** A rating of 4.9 displays 4 fully filled stars and 1 star filled to 90%.

***

## Best Practices

* **Keep reviews authentic** — use real customer quotes when possible
* **Highlight key benefits** — select reviews that mention specific value propositions
* **Limit text length** — shorter reviews are more scannable on mobile
* **Use diverse testimonials** — showcase different use cases and user types
* **Position strategically** — place social proof near purchase decisions
* **Match your app's rating** — use accurate star ratings that reflect your actual store rating
* **Combine formats** — use a Review Line in the header and Review Column below for maximum impact

***

***

[Product Blocks](product-blocks)

[Carousels](carousels)


# Fixing Russian Federation traffic blocking
Source: https://documentation.qonversion.io/docs/solving-russian-federation-traffic-blocking

Resolve Qonversion API access issues in the Russian Federation by configuring a proxy URL during SDK initialization for uninterrupted service.

Due to local regulations in the Russian Federation, certain CloudFlare IPs were blocked, resulting in a partial outage of our API for users in that region. We’ve resolved the issue for most users; however, some may still experience difficulties accessing our API. To ensure full access for everyone, we recommend using the proxy server feature.

To implement it simply provide our proxy URL (`https://api-eu.qonversion.io`) during SDK initialization.

```swift theme={null}
let config = Qonversion.Configuration(projectKey: "projectKey", launchMode: select_needed_launch_mode)
config.setProxyURL("https://api-eu.qonversion.io")
Qonversion.initWithConfig(config)
```

```objectivec theme={null}
QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:select_needed_launch_mode];
[config setProxyURL:@"https://api-eu.qonversion.io"];
[Qonversion initWithConfig:configuration];
```

```java theme={null}
final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
        this,
        "projectKey",
        select_needed_launch_mode
)
        .setProxyURL("https://api-eu.qonversion.io")
        .build();
Qonversion.initialize(qonversionConfig);
```

```kotlin theme={null}
val qonversionConfig = QonversionConfig.Builder(
    this,
    "projectKey",
    select_needed_launch_mode
)
    .setProxyURL("https://api-eu.qonversion.io")
    .build()
```

```dart Flutter theme={null}
final config = new QonversionConfigBuilder(
  'projectKey',
  select_needed_launch_mode
).setProxyURL('https://api-eu.qonversion.io')
 .build();
Qonversion.initialize(config);
```

```javascript React Native theme={null}
const config = new QonversionConfigBuilder(
  'projectKey',
  select_needed_launch_mode
).setProxyURL('https://api-eu.qonversion.io')
 .build();
Qonversion.initialize(config);
```

```csharp Unity theme={null}
QonversionConfig config = new QonversionConfigBuilder(
    "projectKey",
    select_needed_launch_mode
).SetProxyURL("https://api-eu.qonversion.io")
 .Build();
Qonversion.Initialize(config);
```

```typescript Cordova theme={null}
const config = new Qonversion.ConfigBuilder(
  'projectKey',
  select_needed_launch_mode
).setProxyURL('https://api-eu.qonversion.io')
 .build();
Qonversion.initialize(config);
```

```typescript Capacitor theme={null}
const config = new QonversionConfigBuilder(
  'projectKey',
  select_needed_launch_mode
).setProxyURL('https://api-eu.qonversion.io')
 .build();
Qonversion.initialize(config);
```

Note that thanks to the [offline SDK mode](/docs/offline-sdk-mode), your current users from the Russian Federation won't face any problems — our SDKs will handle purchases, entitlements, and other features using local caches. For new users, the [fallback files ](/docs/system-reliability#fallback-files)feature will also help achieve a seamless experience.

Once your users are able to access our API, all the missing analytics will be restored, and purchases will be handled automatically.


# SplitMetrics Acquire
Source: https://documentation.qonversion.io/docs/splitmetrics

Send in-app subscription and purchases events to SplitMetrics Acquire

## Requirements

1. Before setting up the integration with SplitMetrics Acquire, ensure that you have configured integration with [Apple Search Ads](apple-search-ads) and can view events attributed to this media source on the dashboard.
2. Create [custom conversions](https://help.splitmetrics.com/en/articles/3551808-creating-custom-conversions-to-track-in-app-events) on SplitMetrics Acquire side for your in-app events.

## Configure Integration

1. Navigate to the integrations page in Qonversion and select [SplitMetrics Acquire](https://dash.qonversion.io/app/integration/create?name=split_metrics).
2. Find SplitMetrics Acquire Client ID [following this guide](https://help.splitmetrics.com/en/articles/3551823-how-to-find-my-client-id) (login to a platform is required) and provide it to Qonversion.

<img alt="" />

3. Configure Global Event Preferences:

   * Send Revenue Properties: Leave this enabled to receive revenue values. Disable only if you do not require revenue data.
   * Send Sales as Proceed: Choose whether to send revenue values net of App Stores’ commission (default) or gross.
   * Send Sandbox Events: Activate this toggle if you wish to receive sandbox events during testing.

<img alt="" />

4. Fine-Tune Event Settings: For each event, click More options to configure specific settings:

   * Enable Event: Toggle on to include the event in this integration. Turn it off if you do not need it.
   * Send Revenue: Enable or disable sending revenue for this particular event.

<img alt="" />

5. Save Your Configuration: Ensure that all settings are as desired and click Add new integration+/ Save to apply.

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your SplitMetrics account.
</Check>

<Info>
  ### Notes

  1. You must repeat these steps for each app connected to SplitMetrics Acquire.
  2. Qonversion only supports sending In-App events from users attributed with Apple Search Ads. Install postbacks are not supported.
</Info>

***

[Pushwoosh](pushwoosh)

[Segment](segment)


# Splitting rules
Source: https://documentation.qonversion.io/docs/splitting-rules

Launch A/B experiments with the clear picture of what is going on under the hood.

There is often a need to run a few experiments simultaneously:

* There is enough traffic to validate a few hypotheses at a time.
* There are separate teams responsible for onboarding experience, paywalls, and monetization strategy.

Knowing how Qonversion Experiments distributes users between tests is crucial for your work. Let's consider the main rules and examples demonstrating how users are assigned into variants in Qonversion Experiments.

## General splitting rules

Splitter in Qonversion Experiments works in the following way:

1. At the top of the processing funnel, Splitter receives User\_A.
   * Splitter receives User\_A when the [`remoteConfig` method](launch-experiments#get-your-configuration) is called

2. Splitter sorts experiments with selected **Context key** by **Start date** and checks if User\_A can be assigned to each experiment.

3. When Splitter validates if User\_A matches experiment rules, it checks the following attributes:

   1. Segmentation rules (Country, App version, etc.)
   2. Level of traffic allocation (30%, 50%, 70%, etc.)

4. If User\_A matches segmentation rules, he is assigned to a specific group inside the experiment. Otherwise, Splitter returns to Step #2 to check User\_A against the following experiment in the queue.
   1. Please note, if you have the traffic level in the first launched experiment (sorted by start date) set to 70% and in the second - 30%, that means that your second experiment is exposed for (100% - 70%) \* 30% = 9% of all users. Set the traffic level to 100% for the second experiment in case you want to use all the remaining users from the first experiment. [Below](splitting-rules#example-1) you can find some examples that help understand this approach better.

<Note>
  ### Assignment decisions persist

  Once a user enters an experiment — or is rejected by its traffic gate — that decision is stored. Changing the traffic level later never re-evaluates past decisions: raising it admits only users the experiment has never evaluated, and lowering it does not evict anyone. See [Changing experiment traffic mid-flight](/docs/remote-config-targeting#changing-experiment-traffic-mid-flight).
</Note>

<Info>
  ### Cross-context experiments

  Please note that a User can be assigned to a few experiments with different **Context keys** at a time.

  To turn off exposure to cross-context experiments, please use the [Attached active experiment and Attached experiment context key](launch-experiments#segment-your-users) segmentation options.
</Info>

## Example #1

Let's consider the case of launching two experiments with the same Context key at a time:

1. One for users from the UK, 100% traffic allocation level. Start date = 09.03.23

<img alt="" />

2. One for users from the US. 100% traffic allocation level. Start date = 15.03.23.

<img alt="" />

As a result

* 100% of users from the UK are assigned to experiment #1.
* 100% of users from the US are assigned to experiment #2.
* None of the remaining users have been assigned to experiments with the selected Context key.

## Example #2

Let's consider the case of launching two experiments with the same Context key at a time but with similar segmentation settings:

1. One for users from the UK, 70% traffic allocation level. Start date = 09.03.23

<img alt="" />

2. Another one is for users from the UK as well. 30% traffic allocation level. Start date = 15.03.23.

<img alt="" />

Based on the [General splitting rules](splitting-rules#general-splitting-rules), you have the following distribution picture:

* 70% of users from the UK are assigned to Experiment #1 (with Start date = 09.03.23).
* (100% - 70%) \* 30% = 9% of users from the UK are assigned to Experiment #2 (with Start date = 15.03.23).
* 100% - 70% - 9% = 21% of users from the UK are not assigned to any experiment.
* 100% of users outside the UK have not been assigned to experiments with the selected Context key.

***

[Stop experiments](finish-experiment)

[Apple App Store](apple-app-store)


# Store Product Price Changes
Source: https://documentation.qonversion.io/docs/store-product-price-changes

Understand how subscription price changes are handled on the App Store and Google Play, and how they affect existing subscribers and new users.

## App Store

When you increase a subscription price, Apple informs affected subscribers via email and push notification and asks them to agree to the new price.

On iOS 13.4 and iPadOS 13.4 and later, affected subscribers are also notified through a price consent sheet that automatically displays in your app. If they disagree, their subscription expires at the end of their current billing cycle.

## Google Play Store

After you change the price of an existing subscription, here’s how it affects new users and existing subscribers:

* New users can immediately see the subscription’s new price and subscribe to it on Google Play.

* Existing subscribers receiving a price increase will be notified of the price change by email and through a notification on Google Play 7 days after the price change occurs. Subscribers will then have 30 days to agree to the price change. Otherwise, their subscription will be cancelled on their next renewal date.

## Qonversion Price Changes

Qonversion tracks prices at the moment of purchase and assumes any subscriptions will renew at this purchase price. If you change the product price, the existing subscription will be renewed for the previous price, but all new clients will be charged the new price.

Kindly note that if you ever raise the price of a product, Qonversion data will be accurate if you decide to keep your existing subscriptions at the current price.

<Info>
  ### ☝️

  We recommend creating a new product instead of changing the price of an existing product for the correct data display.
</Info>

***

[Non-Subscription Purchases](non-subscription-purchases)

[Upgrade and Downgrade a Subscription](upgrade-and-downgrade-a-subscription)


# StoreKit testing in Xcode
Source: https://documentation.qonversion.io/docs/storekit-testing-in-xcode

Set up and test in-app purchases with a StoreKit Configuration file in Xcode together with Qonversion: create the file, export its public certificate, upload it to the Dashboard, run test purchases, and clear the test data afterwards.

StoreKit Configuration files in Xcode let you test in-app purchases locally, without connecting to App Store servers. Upload the file's public certificate to Qonversion and your local test purchases flow through Qonversion just like real ones — entitlements, analytics, and webhooks all work.

<Note>
  Uploading a certificate does not affect real users. Production receipts signed by Apple keep validating through Apple; the certificate is only used to validate receipts produced by your StoreKit Configuration file.
</Note>

Official Apple guide: [Setting up StoreKit testing in Xcode](https://developer.apple.com/documentation/xcode/setting-up-storekit-testing-in-xcode/).

## 1. Create a StoreKit Configuration file

<Steps>
  <Step title="Add the file">
    In Xcode, go to **File → New → File from Template**, search for *StoreKit*, and choose **StoreKit Configuration File**. Save it.
  </Step>

  <Step title="Add your products">
    Inside the `.storekit` file, add the in-app products you want to test — consumables, non-consumables, and auto-renewable subscriptions.
  </Step>

  <Step title="Attach it to your scheme">
    Open **Product → Scheme → Edit Scheme… → Run → Options → StoreKit Configuration** and select your `.storekit` file.
  </Step>
</Steps>

## 2. Export the public certificate

Qonversion needs the public certificate from your StoreKit Configuration file to validate transactions.

<Steps>
  <Step title="Select the file">
    In Xcode's Project navigator, select the `.storekit` file.
  </Step>

  <Step title="Save the certificate">
    From the menu bar choose **Editor → Save Public Certificate** and save the `.cer` file locally.
  </Step>
</Steps>

## 3. Upload the certificate to Qonversion

<Steps>
  <Step title="Open Stores settings">
    In the Qonversion Dashboard go to **Project Settings → Stores**.
  </Step>

  <Step title="Add the certificate">
    In the **Apple App Store** card click **Add certificate**, then drop or select your `.cer` file in the panel that opens.
  </Step>
</Steps>

Once uploaded, the **StoreKit test certificate** chip turns green. To stop accepting StoreKit Configuration receipts, click **Remove** on that chip.

<Note>
  Only `.cer` and `.pem` public certificates are accepted — never upload a private key or an Apple production certificate.
</Note>

## 4. Run test purchases

Run your app in the Simulator or on a device using the scheme with your StoreKit Configuration file, and buy products as usual. Qonversion validates each transaction with your uploaded certificate, so local test purchases grant entitlements and appear in analytics just like real ones.

<Warning>
  If you set an **accelerated subscription renewal rate** in your StoreKit Configuration file, we strongly recommend **not** reusing the same test account. Accelerated renewals create a new transaction every few seconds, so that account piles up test data very quickly.

  Periodically **reinstall the app** to start fresh from a new `clientUid` and keep accounts from getting cluttered. For ordinary test cases (no accelerated renewals) this isn't needed — data won't accumulate.
</Warning>

## 5. Manage and clear test data

Purchases made through your StoreKit Configuration certificate are tagged **sandbox** and show up in your test-mode analytics next to Apple Sandbox purchases. They are **not** removed when you reset StoreKit in Xcode.

<Warning>
  Use a separate `clientUid` (user identifier) in your test build so StoreKit test data stays isolated from your real customers.
</Warning>

To clear StoreKit test data from Qonversion:

* **The whole project** — on the **Customers** page, open the ⚙ chart settings and choose **Reset StoreKit test data**.
* **A single customer** — open the customer and use **Reset StoreKit test data** next to the sandbox icon.

This removes only purchases made through the StoreKit Configuration certificate. Apple Sandbox, TestFlight, and real App Store purchases are never affected.


# Stripe Integration
Source: https://documentation.qonversion.io/docs/stripe-integration

Connect your Stripe account to Qonversion to manage cross-platform subscribers and track analytics for web payments.

Qonversion supports Stripe web payments. This integration allows Qonversion to manage cross-platform subscribers' access and provide analytics for payments made via Stripe on your website.

<Info>
  In case you are selling digital goods, you can not promote web payment options in your mobile app as it goes against the app stores' policies.
</Info>

## 1. Connect your Stripe account to Qonversion

Click the **Stripe** button in the Stores tab of your project settings in [Qonversion dashboard](https://dash.qonversion.io/project-settings/stores).

<Frame>
  <img />
</Frame>

Sign in using your existing Stripe account or create a new one. These options will be offered during the integration process.

<Info>
  Qonversion only retrieves information from Stripe and does not update anything in your Stripe account. You have complete control over your Stripe account and can revoke access whenever you want.
</Info>

## 2. Create Stripe products

You can create products using Stripe [dashboard:](https://dashboard.stripe.com/products/create)

<Frame>
  <img />
</Frame>

A product can have multiple prices — more about setting up Stripe products in [Stripe official documentation](https://stripe.com/docs/billing)

<Warning>
  Qonversion currently supports only Package and Standard pricing models.
</Warning>

You can use the Stripe dashboard to create a subscription manually, but the most common way is to use Stripe checkout on your website to get the customer payment information and send it to your server. You can check the details of working with Stripe subscriptions using REST API [here](https://stripe.com/docs/api/)

## 3. Add your Stripe products to Qonversion

<Info>
  Skip this step if you are not using the [Qonversion Subscription Management mode](subscription-management-mode).
</Info>

Add your Stripe products to the [dashboard](https://dash.qonversion.io/entitlements/products) to manage cross-platform subscribers' access.

<Frame>
  <img />
</Frame>

Make sure that the Stripe Product Identifier that you provide to Qonversion matches your Product ID in Stripe. You can find your Product ID in Stripe via the product [page](https://dashboard.stripe.com/products).

<Frame>
  <img />
</Frame>

## 4. Send Stripe purchases to Qonversion

For instance, let's use the [Prebuilt subscription page with Stripe Checkout](https://stripe.com/docs/billing/quickstart)

1. Add param `product_id` (in our case it's equal to `prod_LnoFij9PJ9OvK2`) to the Success URL. `/success?session_id={CHECKOUT_SESSION_ID}&product_id=prod_LnoFij9PJ9OvK2`

2. In the Success URL handler retrieve the Stripe Session data via [Stripe API](https://stripe.com/docs/api/checkout/sessions/retrieve). Let's name it `stripe_session`. Additional information about success page customization is specified on the Stripe docs page [Customise your success page](https://stripe.com/docs/payments/checkout/custom-success-page)

3. Send your Stripe purchase result to Qonversion via the [API endpoint](/reference/overview).

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.qonversion.io/v3/users/{user_id}/purchases \
    --header 'Authorization: Bearer PROJECT_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "currency": "USD",
      "price": "11.99",
      "purchased": 1653458781,
      "stripe_store_data": {
        "subscription_id": "sub_XXXXXX",
        "product_id": "prod_LnoFij9PJ9OvK2"
      }
    }'
  ```
</CodeGroup>

| Qonversion request field             | Source                                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| currency                             | stripe\_session.currency                                                                       |
| price                                | stripe\_session.amount\_total                                                                  |
| purchased                            | Unix-epoch seconds when the Stripe Checkout Session completed (e.g. `stripe\_session.created`) |
| stripe\_store\_data.subscription\_id | stripe\_session.subscription.id                                                                |
| stripe\_store\_data.product\_id      | GET parameter product\_id from the Success URL                                                 |

Qonversion updates data on Stripe subscriptions automatically. Usually, it happens with a slight delay compared to its actual state in Stripe.

## Limitations

**Supported subscription billing models**

Only the Package and Standard pricing subscription billing models are supported. We will be expanding to more pricing options soon!

You can read more about subscription billing models in [Stripe official documentation](https://stripe.com/docs/billing/subscriptions/model).

**Proration payments**

Subscription changes such as upgrading or downgrading can result in prorated charges. Qonversion will not account for these charges in revenue calculations. It would be best to disable these options manually via the Stripe dashboard. You can also disable them by setting the `proration_behavior` attribute to `"none"` via the Stripe API (other accepted values are `"create_prorations"` - the default - and `"always_invoice"`).

**Cancellations**

Stripe has two subscription cancellation options:

1. *Immediate cancellation*: subscription cancels immediately with or without any proration option
2. *Cancellation at the end of the period*: The subscription cancels at the end of the current billing period (similar to in-app subscriptions on the app stores).

Qonversion supports both options, but the revenue calculation for immediate cancellation will disregard the proration option.

**Coupons, discounts, and price changes**

Qonversion will take into account price changes, including manual updates or coupons, applied by customers in subscription revenue calculation.

**Refunds**

Qonversion tracks only full refunds. Proration or partial refunds are not supported currently.

***

[Google Play Product Details](google-play-product-details)

[Web SDK](web-sdk)


# Subscription Management Mode
Source: https://documentation.qonversion.io/docs/subscription-management-mode

This guide is for implementing subscription-based access management with Qonversion (Subscription Management mode).

The Subscription Management mode allows you to implement a complete cycle of in-app purchases management: getting offers, making (or restoring) purchases, and handling entitlements.

If you want only to get a single source of truth for revenue analytics and leverage [real-time purchase events](integrations-overview#tracked-events) in integrations, please refer to the [Analytics Mode guide](analytics-mode).

## 1. Configure Products & Entitlements

To successfully run subscription-based entitlement management, you need to connect stores' products to Qonversion:

1. Create and configure in-app products on the [App Store Connect](https://qonversion.io/blog/configure-iap-app-store-connect/) and/or [Google Play Console](android-in-app-products) sides

   * Please note that your *App Store Connect* products must be in either *Ready to submit* or *Ready for sale* statuses. Otherwise, the [*Product not found error*](troubleshooting#product-not-found-error) may occur during Qonversion SDK integration.
   * Do not forget to activate your products for the Google Play console. Otherwise, the [*SkuDetails error*](troubleshooting#skudetails-error) may occur during Qonversion SDK integration.

2. [Create entitlement](https://dash.qonversion.io/entitlements) which should be granted once in-app product is purchased. Learn more about Qonversion entitlements [here](entitlements).

3. [Create product-linker](https://dash.qonversion.io/entitlements/products) in Qonversion and link it to the previously created entitlement. Learn more about Qonversion products [here](create-products).

<Info>
  Selling on the web too? You can map web-billing products into the same entitlements. Connect [Stripe](stripe-integration) or [Paddle](paddle-integration) and add their product IDs to your Qonversion products so cross-platform subscribers get the same access.
</Info>

## 2. Configure a Remote Config for your paywall (optional)

To change the set of products offered to your users without an app release, put your product IDs into a [Remote Config](remote-config) and read it in the app. This also lets you target user segments and [run A/B tests](launch-test-from-remote-config) on your paywall later. See the [recommended payload structure and code samples](migrate-offerings-to-remote-configs).

This step is not required for Subscription Management Mode — you can also [request your products directly](displaying-products#get-the-list-of-available-products).

## 3. Launch SDK

Initialize the SDK in Subscription Management mode:

<InitSdk />

**→[Get your Qonversion Project Key](quickstart#2-create-a-project-and-register-your-app)**

## 4. Set additional user attributes

Optionally, to improve attribution in Adjust, AppsFlyer, Singular, or to match Qonversion revenue events to users in [third-party tools](integrations-overview), you can share with us such attributes as User Identifier, IDFA (Identifier for Advertisers, iOS 14.5+ only) or ASID (App set ID, Android 12+ only). Please follow [this guide](user-properties#custom-user-properties) to learn more.

## 5. Display products, make purchases, and check the premium status

Once you have added Products and Entitlements to Qonversion, initialized the SDK, and added user attributes, it's time to proceed to the main part of the Subscription Management implementation!

1. [Here](displaying-products) you'll learn how to correctly display products to your customer using Qonversion SDK.
2. By following [this guide](making-purchases), you will know how to launch a purchase, after which your user gets premium access with the entitlement you have created above.
3. Finally, [this article](check-permissions) will help you check whether your user has already been granted access to your premium features.

***

## Next steps

With products, entitlements, and the SDK in place, wire up the purchase flow and verify access.

<NextStepsSubscription />


# Subscriptions
Source: https://documentation.qonversion.io/docs/subscriptions

Track active, new, and churned paid subscriptions with analytics on subscription movement and cancellation rates.

## Active Subscriptions

The Active Subscriptions chart shows the number of active paid subscriptions at the selected dates. This chart includes only paid subscriptions, i.e. it does not include free trials. The Active Subscriptions chart shows the subscriptions split by their auto-renewable state. When a user cancels an auto-renewable subscription on the app store, it is still active till the expiration date.

The chart's title shows your active subscriptions at the end of the selected period, and the percentage reflects the change in subscriptions during the period chosen. In the example below, for the 30th of June, you have 21,438 active paid subscriptions, which is 17.6% higher than you had for the 1st of June.

<Frame>
  <img />
</Frame>

<Info>
  ### Subscriptions in the Billing Retry state

  A subscription can be in the [Billing Retry](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/reducing_involuntary_subscriber_churn) and [Account Hold](https://developer.android.com/google/play/billing/subscriptions#account-hold) states on the App Store and Google Play, respectively. These states help reduce subscribers' involuntary churn. Users no longer have premium access in these states. Qonversion excludes such subscriptions from the Active Subscriptions chart.

  If a **billing grace period** is configured in your store settings ([App Store Connect](https://developer.apple.com/help/app-store-connect/manage-subscriptions/enable-billing-grace-period-for-auto-renewable-subscriptions) or [Google Play Console](https://support.google.com/googleplay/android-developer/answer/9383573)), Qonversion extends the subscription's active window by the grace period duration before counting it as churned. This affects the Active Subscriptions, Subscriptions Movement, [MRR/ARR](revenue), and [Cohorts](cohorts) charts:

  * Subscriptions with a grace period continue to count as active and appear as churned only after the grace period expires, not at the moment billing retry begins.
  * Subscriptions without a grace period are counted as churned at the end of the last paid period.
</Info>

## New Subscriptions

The New Subscriptions chart shows paid subscribers added for the selected period. The chart includes users who started subscriptions and converted from a free trial.

The chart's title displays the total amount of new paid subscriptions during the selected period; the percentage shows how it changed compared to the previous period of the same length.

<Frame>
  <img />
</Frame>

## Subscriptions Movement

Subscriptions Movement helps you understand how your subscriber base changes over time. This chart shows new paid subscriptions (above zero), and subscriptions churned (below zero), i.e., expired or refunded subscriptions.

Please note that the subscription cancellation, i.e., turning off auto-renewal, does not mean the subscription has churned. Such subscriptions show up as churned in this chart only once they expire. Additionally, if a user did not cancel a subscription, but a platform (Apple/Google) can not renew a subscription due to lack of funds or incorrect payment details provided by a user, this subscription expires after being in a billing issue state for some time. A refund requested by a user immediately leads to subscription expiration.

The chart's title shows the net number of new paid subscriptions during the selected period; the percentage shows how this value changed compared to the previous period of the same length. In the example below, the subscription base increased by 3,770 active paid subscriptions, which is 5.59% higher than your growth in the previous period of the same length (31 days).

<Frame>
  <img />
</Frame>

## Subscriptions Cancellation Rate

The Subscriptions Cancellation Rate is calculated as the ratio of: → Numerator: subscription cancelled events attributed to subscription start date → Denominator: subscriptions started events for the selected period

<Frame>
  <img />
</Frame>

***

[Trials](trials)

[Events](events-analytics)


# Success and Failure Actions
Source: https://documentation.qonversion.io/docs/success-failure-actions

Configure custom behaviors after purchase or restore actions complete.

## Overview

Success and Failure Actions allow you to define custom behaviors that occur after a purchase or restore action completes in your No-Code screens.

By default:

* **On Success**: The screen closes (`Close All`)
* **On Failure**: Nothing happens, the user stays on the screen (`None`)

With custom Success/Failure Actions, you can override these defaults to create more engaging user experiences.

***

## Available Actions

The following actions can be configured as Success or Failure handlers:

| Action         | Description                                         |
| -------------- | --------------------------------------------------- |
| **None**       | Do nothing, stay on the current screen              |
| **Close**      | Close the current screen only                       |
| **Close All**  | Close all No-Code screens                           |
| **Navigate**   | Navigate to another No-Code screen                  |
| **Open URL**   | Open a URL in the browser                           |
| **Deep Link**  | Open a deep link in your app                        |
| **Go to Page** | Navigate to another page within a multi-page screen |

***

## Supported Actions

Success and Failure handlers can be configured for the following actions:

* **Make Purchase** — triggered when a user initiates a product purchase
* **Restore** — triggered when a user restores previous purchases

***

## Platform-Specific Configuration

When **Platform-Specific Actions** is enabled, you can configure different Success/Failure behaviors for iOS and Android platforms independently.

***

## Minimum SDK Versions

Success and Failure Actions require the following minimum SDK versions:

| Platform     | Minimum Version |
| ------------ | --------------- |
| iOS          | 6.5.0           |
| Android      | No-Codes 1.5.0  |
| Flutter      | 11.3.0          |
| React Native | 10.3.0          |
| Unity        | 9.2.0           |
| Cordova      | 7.2.0           |
| Capacitor    | 1.2.0           |

<Info>
  ### **Note**

  If you're using an older SDK version, the default behavior will be applied:

  * Success: Close all screens
  * Failure: Stay on the screen
</Info>

***

## Configuration

To configure Success/Failure Actions in the No-Code Builder:

1. Select a component with a **Make Purchase** or **Restore** action

2. In the **Action** section of the right sidebar, you'll see:

   * **On Success** — action to execute after successful completion
   * **On Failure** — action to execute after failure

3. Select the desired action for each case

4. If the action requires a value (e.g., URL, screen ID), enter it in the corresponding field

![Success/Failure Actions Configuration](https://files.readme.io/placeholder-success-failure-actions.png)

***

## Best Practices

* **Success Actions**: Consider navigating to a thank-you screen or closing all screens to return users to your app
* **Failure Actions**: Keep users on the screen (`None`) so they can retry, or navigate to a help/support screen
* **Platform Differences**: Use platform-specific actions when iOS and Android require different post-purchase flows

***

[Displaying No-Codes](displaying-no-codes)

[Using No-Codes with custom purchases handling](using-no-codes-with-custom-purchases-handling)


# Migrate from SwiftyStoreKit
Source: https://documentation.qonversion.io/docs/swiftystorekit-alternative

Migrate your app from SwiftyStoreKit to Qonversion

Qonversion provides server-side receipt validation, real-time app monitoring, subscription analytics, integrations with the leading mobile platforms, and more. You can easily migrate from SwiftyStoreKit to Qonversion. Qonversion is probably the best SwiftyStoreKit alternative.

<Frame>
  <img />
</Frame>

## Why migrate from SwiftyStoreKit?

Qonversion makes it easy to get the list of available in-app products, make and restore purchases, check user entitlements, and validate user receipts. Server-side receipt validation guarantees the entitlements' accuracy. Unlike with SwiftyStoreKit, you don't need to worry about storing the information on user subscriptions. Qonversion handles entitlement logic and provides simple methods to get accurate user entitlements with just a few lines of code. Qonversion provides a cross-platform subscription infrastructure for iOS, Android, and web apps, so it's really easy to handle end-user access across mobile and desktop apps.

You can learn more about Qonversion [products & entitlements here](product-center).

## SwiftyStoreKit Migration Steps

## 1. App start

#### SwiftyStoreKit

<CodeGroup>
  ```swift Swift theme={null}
  func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  	// see notes below for the meaning of Atomic / Non-Atomic
  	SwiftyStoreKit.completeTransactions(atomically: true) { purchases in
  	    for purchase in purchases {
  	        switch purchase.transaction.transactionState {
  	        case .purchased, .restored:
  	            if purchase.needsFinishTransaction {
  	                // Deliver content from server, then:
  	                SwiftyStoreKit.finishTransaction(purchase.transaction)
  	            }
  	            // Unlock content
  	        case .failed, .purchasing, .deferred:
  	            break // do nothing
  	        }
  	    }
  	}
      return true
  }
  ```
</CodeGroup>

#### Qonversion

<CodeGroup>
  ```swift Swift theme={null}
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
      let config = Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
      Qonversion.initWithConfig(config)

      return true
  }
  ```

  ```objectivec Objective-C theme={null}
  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  		QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
      [Qonversion initWithConfig:configuration];

      return YES;
  }
  ```
</CodeGroup>

##### **Migration Step:**

Remove the SwiftyStoreKit `completeTransactions()` method, and replace it with the Qonversion SDK `launch()` method.

## 2. Load products

#### SwiftyStoreKit

<CodeGroup>
  ```swift Swift theme={null}
  SwiftyStoreKit.retrieveProductsInfo(["com.musevisions.SwiftyStoreKit.Purchase1"]) { result in
      if let product = result.retrievedProducts.first {
          let priceString = product.localizedPrice!
          print("Product: \(product.localizedDescription), price: \(priceString)")
      }
      else if let invalidProductId = result.invalidProductIDs.first {
          print("Invalid product identifier: \(invalidProductId)")
      }
      else {
          print("Error: \(result.error)")
      }
  }
  ```
</CodeGroup>

#### Qonversion

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().products { productsList, error in
      let product = productsList["main"]
      if product?.type == .trial {
      
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] products:^(NSDictionary<NSString *,QONProduct *> * _Nonnull productsList, NSError * _Nullable error) {
      if (error) {
        // Handle error
      }
      QONProduct *product = productsList[@"main"];
      if (product && product.type == QONProductTypeTrial) {

      }
  }];
  ```
</CodeGroup>

##### Migration Step:

[Products](https://dash.qonversion.io/app/product-center) are configured in the Qonversion [dashboard](https://dash.qonversion.io) for Qonversion SDK and mapped to SKProducts. Configure the products in Qonversion, then replace `retrieveProductsInfo()` in SwiftyStoreKit with `products()` in Qonversion SDK.

## 2. Making a purchase

#### SwiftyStoreKit

<CodeGroup>
  ```swift Swift theme={null}
  SwiftyStoreKit.purchaseProduct("com.musevisions.SwiftyStoreKit.Purchase1", quantity: 1, atomically: true) { result in
      switch result {
      case .success(let purchase):
          print("Purchase Success: \(purchase.productId)")
      case .error(let error):
          switch error.code {
          case .unknown: print("Unknown error. Please contact support")
          case .clientInvalid: print("Not allowed to make the payment")
          case .paymentCancelled: break
          case .paymentInvalid: print("The purchase identifier was invalid")
          case .paymentNotAllowed: print("The device is not allowed to make the payment")
          case .storeProductNotAvailable: print("The product is not available in the current storefront")
          case .cloudServicePermissionDenied: print("Access to cloud service information is not allowed")
          case .cloudServiceNetworkConnectionFailed: print("Could not connect to the network")
          case .cloudServiceRevoked: print("User has revoked permission to use this cloud service")
          default: print((error as NSError).localizedDescription)
          }
      }
  }
  ```
</CodeGroup>

#### Qonversion

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().purchase(product) { (result) in
    if result.isSuccessful {
      if let premium: Qonversion.Entitlement = result.entitlements["premium"], premium.isActive {
        // Grant user access to premium features
      }
    } else if result.isCanceledByUser {
      // `paymentCancelled` analogue
    } else if result.isPending {
      // Handle pending purchase
    } else {
      if let error = result.error as NSError? {
        let skError = SKError(_nsError: error)

        switch skError.code {
        case .unknown: print("Unknown error")
        case .clientInvalid: print("Not allowed to make the payment")
        case .paymentInvalid: print("The purchase identifier was invalid")
        case .paymentNotAllowed: print("The device is not allowed to make the payment")
        case .storeProductNotAvailable: print("The product is not available in the current storefront")
        case .cloudServicePermissionDenied: print("Access to cloud service information is not allowed")
        case .cloudServiceNetworkConnectionFailed: print("Could not connect to the network")
        case .cloudServiceRevoked: print("User has revoked permission to use this cloud service")
        default: print((error as NSError).localizedDescription)
        }
      }
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] purchaseWithResult:product completion:^(QONPurchaseResult * _Nonnull result) {
    if (result.isSuccessful) {
      QONEntitlement *premiumEntitlement = result.entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        // Grant user access to premium features
      }
    } else if (result.isCanceledByUser) {
      // `paymentCancelled` analogue
    } else if (result.isPending) {
      // Handle pending purchase
    } else {
      if (result.error) {
        case QONErrorCodeUnknown:
          NSLog(@"Unknown error");
          break;
        case QONErrorCodeClientInvalid:
          NSLog(@"Not allowed to make the payment");
          break;
        case QONErrorCodePaymentInvalid:
          NSLog(@"The purchase identifier was invalid");
          break;
        case QONErrorCodePaymentNotAllowed:
          NSLog(@"The device is not allowed to make the payment");
          break;
        case QONErrorCodeStoreProductNotAvailable:
          NSLog(@"The product is not available in the current storefront");
          break;
        case QONErrorCodeCloudServicePermissionDenied:
          NSLog(@"Access to cloud service information is not allowed");
          break;
        case QONErrorCodeCloudServiceNetworkConnectionFailed:
          NSLog(@"Could not connect to the network");
          break;
        case QONErrorCodeCloudServiceRevoked:
          NSLog(@"User has revoked permission to use this cloud service");
          break;
        default:
          NSLog(@"%@", error.localizedDescription);
          break;
      }
    }
  }
  ```
</CodeGroup>

##### Migration Step:

Purchases are initiated from a product ID or a SKProduct in SwiftyStoreKit. In Qonversion purchases should be initiated from [Qonversion Product](products) id. Replace the SwiftyStoreKit `purchaseProduct()` method with `purchase()`. Pass the Qonversion product id that was loaded previously.

You don't need to parse through SKError to check if the user has cancelled the payment. The property `cancelled` is provided in the callback for that case.

Confirm that the subscription has been purchased by checking if the `entitlements` object contains an active entitlement for the **premium** content you configured in the [Qonversion dashboard](https://dash.qonversion.io).

## 3. Restore previous purchases

#### SwiftyStoreKit

<CodeGroup>
  ```swift Swift theme={null}
  SwiftyStoreKit.restorePurchases(atomically: true) { results in
      if results.restoreFailedPurchases.count > 0 {
          print("Restore Failed: \(results.restoreFailedPurchases)")
      }
      else if results.restoredPurchases.count > 0 {
          print("Restore Success: \(results.restoredPurchases)")
      }
      else {
          print("Nothing to Restore")
      }
  }
  ```
</CodeGroup>

#### Qonversion

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().restore { [weak self] (entitlements, error) in
      if let error = error {
        // Handle error
      }
    
      if let entitlement: Qonversion.Entitlement = entitlements["plus"], entitlement.isActive {
          // Restored and entitlement is active 
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] restore:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull result, NSError * _Nullable error) {
      if (error) {
        // Handle error
      }
      QONEntitlement *entitlement = result[@"active"];
      if (entitlement && entitlement.isActive) {
        // Restored and entitlement is active
      }
  }];
  ```
</CodeGroup>

##### Migration step:

Just replace the SwiftyStoreKit `restorePurchases` with Qonversion `restore` method.

## 3. Handling purchases started on the App Store (iOS 11 or later)

Unlike SwiftyStoreKit, Qonversion SDK supports App Store promoted in-app purchases including delayed promoted purchases or making a purchase after specific checks. For example, if you don't want to show the purchase screen to the user before your app's onboarding, you can delay the purchase and call it when needed. Let's have a look at the example below:

#### SwiftyStoreKit

<CodeGroup>
  ```swift Swift theme={null}
  SwiftyStoreKit.shouldAddStorePaymentHandler = { payment, product in
      // return true if the content can be delivered by your app
      // return false otherwise
  }
  ```
</CodeGroup>

#### Qonversion

By default App Store promoted purchases will be enabled, and purchasing flow will run on the app start. If you need additional logic set `QONPromoPurchasesDelegate`:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setPromoPurchasesDelegate(self)
  ```

  ```text Objective-C theme={null}
  [[Qonversion sharedInstance] setPromoPurchasesDelegate:self];
  ```
</CodeGroup>

Then implement the delegate function:

<CodeGroup>
  ```swift Swift theme={null}
  func shouldPurchasePromoProduct(withIdentifier productID: String, executionBlock: @escaping Qonversion.PromoPurchaseCompletionHandler) {
      // check AppStore productID value in case you want to enable promoted purchase only for specific products
      
      let completion: Qonversion.PurchaseCompletionHandler = {result, error, flag in
        // handle purchased product or error
      }
      
      // call this block if you want to allow promoted purchase or just store the block and call when needed
      // do nothing and do not call the block if you don't want to allow the purchase
      executionBlock(completion)
  }
  ```
</CodeGroup>

#### Migration step:

App Store promotional offers support is available by default. If you need additional logic, then use `setPromoPurchasesDelegate()` and the function `shouldPurchasePromoProduct()`

## 4. Receipt verification and user entitlements

#### SwiftyStoreKit

Receipt verification is done locally in SwiftyStoreKit. This might lead to inaccurate subscription status data and is not recommended by Apple.

<CodeGroup>
  ```swift Swift theme={null}
  let appleValidator = AppleReceiptValidator(service: .production, sharedSecret: "your-shared-secret")
  SwiftyStoreKit.verifyReceipt(using: appleValidator) { result in
      switch result {
      case .success(let receipt):
          let productId = "com.musevisions.SwiftyStoreKit.Subscription"
          // Verify the purchase of a Subscription
          let purchaseResult = SwiftyStoreKit.verifySubscription(
              ofType: .autoRenewable, // or .nonRenewing (see below)
              productId: productId,
              inReceipt: receipt)
              
          switch purchaseResult {
          case .purchased(let expiryDate, let items):
              print("\(productId) is valid until \(expiryDate)\n\(items)\n")
          case .expired(let expiryDate, let items):
              print("\(productId) is expired since \(expiryDate)\n\(items)\n")
          case .notPurchased:
              print("The user has never purchased \(productId)")
          }

      case .error(let error):
          print("Receipt verification failed: \(error)")
      }
  }
  ```
</CodeGroup>

#### Qonversion

Qonversion provides server-side receipt validation out-of-the-box. You can check the user subscription status as follows:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().checkEntitlements { (entitlements, error) in
    if let error = error {
      // handle error
      return
    }
    
    if let premium: Qonversion.Entitlement = entitlements["premium"], premium.isActive {
      switch premium.renewState {
        case .willRenew, .nonRenewable:
          // .willRenew is the state of an auto-renewable subscription 
          // .nonRenewable is the state of consumable/non-consumable IAPs that could unlock lifetime access
          break
        case .billingIssue:
          // Grace period: entitlement is active, but there was some billing issue.
          // Prompt the user to update the payment method.
          break
        case .cancelled:
          // The user has turned off auto-renewal for the subscription, but the subscription has not expired yet.
          // Prompt the user to resubscribe with a special offer.
          break
        default: break
      }
    }
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] checkEntitlements:^(NSDictionary<NSString *, QONEntitlement *> * _Nonnull entitlements,
                                  NSError * _Nullable error) {
      QONEntitlement *premiumEntitlement = entitlements[@"premium"];
      if (premiumEntitlement && premiumEntitlement.isActive) {
        switch (premiumEntitlement.renewState) {
          case QONEntitlementRenewStateWillRenew:
          case QONEntitlementRenewStateNonRenewable:
            // QONEntitlementRenewStateWillRenew is state for auto-renewable purchases
            // QONEntitlementRenewStateNonRenewable is state for in-app purchases that unlock the entitlement lifetime
            break;
          case QONEntitlementRenewStateBillingIssue:
            // Grace period: entitlement is active, but there was some billing issue.
            // Prompt the user to update the payment method.
            break;
          case QONEntitlementRenewStateCancelled:
            // The user canceled the subscription, but the subscription has not expired yet.
            // Prompt the user to resubscribe with some special offer.
            break;
          default:
            break;
        }
      }
  }];
  ```
</CodeGroup>

## Active Subscriptions Migration

There are several ways to transmit the data on subscribers that have already purchased a subscription using SwiftyStoreKit to Qonversion.

##### 1. First option

Provide your users with a [restore purchase](swiftystorekit-alternative#qonversion-3) option. For example, you can direct them to the screen where restore purchase is available. Qonversion will get all the required data including the historical data for analytics once the subscription is restored.

##### 2. Second option

Trigger [restore purchase](swiftystorekit-alternative#qonversion-3) automatically for users, who subscribed using SwiftyStoreKit. This will get all the required data. Please note, triggering restore will prompt a user to sign in to their Apple ID if they are not signed in already. So you need to trigger restore only once. Here is the code sample showing how to check and save in UserDefaults that a purchase has been restored for a user:

<CodeGroup>
  ```swift Swift theme={null}
  let keyForMigrated = "isMigratedFromSwiftyStoreKit"
  let isMigrated = UserDefaults.standard.bool(forKey: keyForMigrated)

  if isMigrated == false {
    Qonversion.restore { (_, _) in }
    UserDefaults.standard.setValue(true, forKey: keyForMigrated)
  }
  ```

  ```objectivec Objective-C theme={null}
  NSString *keyForRestoredFlag = @"isRestored";
  BOOL isRestored = [[NSUserDefaults standardUserDefaults] boolForKey:keyForRestoredFlag];

  if (isRestored == false) {
    [Qonversion restore:^(NSDictionary<NSString *,QONEntitlement *> * _Nonnull result, NSError * _Nullable error) {}];
    [[NSUserDefaults standardUserDefaults] setBool:YES forKey:keyForRestoredFlag];
  }
  ```
</CodeGroup>

##### 3. Third option

If you have user receipts stored on your backend, you can [contact us](https://qonversion.io/contact-us) and we will import them into Qonversion.

***

What’s Next

You can check the sample iOS app with Qonversion implementation or watch the video tutorial:

* [Sample App](sample-apps)
* [Tutorials](tutorials)


# System Reliability
Source: https://documentation.qonversion.io/docs/system-reliability

At Qonversion, reliability has always been our priority. We have multiple protection mechanisms that allow us to avoid any downtimes and provide a reliable in-app subscription management service SLA. These mechanisms can be categorized into three levels:

* Internal infrastructure reliability
* External backend-replacement service
* SDK-level protection

## Aegis

We have an independent service called Aegis, based on Cloudflare infrastructure, that can replace our API if our internal infrastructure fails. Aegis responds just like our main API. We prepare necessary caches in Cloudflare’s storage from our database while it's operational. During an outage, incoming traffic is redirected to a Cloudflare Worker that handles requests using cached data. It also queues incoming requests to resend to the API once it's back online to update our database. This is all based on Cloudflare's infrastructure, which guarantees 100% SLA. [Read more here.](https://qonversion.io/blog/most-reliable-in-app-subscription-management-service/#3)

## Fallback files

The Fallback Files feature in Qonversion ensures data reliability and continuity by maintaining backup files directly within the SDK for critical functionalities like purchases and remote configs. In the event of a network provider error or system failure, these files allow the SDK to preserve essential operations, ensuring that purchases in stores can still be completed successfully. This feature is crucial for maintaining high availability and a seamless user experience, even under adverse conditions.

### How to Set Up Fallback Files

**Download Fallback File**

To set up Fallback Files, navigate to either the [Entitlements](https://dash.qonversion.io/entitlements) or [Remote Configs](https://dash.qonversion.io/remote-configs) section in your Qonversion dashboard and click the Fallbacks button to download the file. The configuration content is the same in both sections.

<iframe />

<Warning>
  ### **Do not change** the name of the file you downloaded from the Qonversion dashboard.
</Warning>

#### iOS

Place the fallback file into the project directory, and Qonversion **will automatically detect** and utilize it.

#### Android

Place the fallback file in the `main/assets` directory and Qonversion **will automatically detect** and utilize it.

If you prefer to store resources in the `res/raw` directory, you can certainly keep the fallback file there. However, in this scenario, you’ll need to explicitly inform the Qonversion SDK about the fallback file’s location.

Use the following code to set a fallback file:

<CodeGroup>
  ```kotlin Kotlin theme={null}
  val config = QonversionConfig.Builder(this, "your_project_key",QLaunchMode.SubscriptionManagement)
    .setFallbackFileIdentifier(R.raw.qonversion_android_fallbacks)
    .build()
  ```

  ```java Java theme={null}
  final QonversionConfig qonversionConfig = new QonversionConfig.Builder(this,"your_project_key",QLaunchMode.SubscriptionManagement)
  	.setFallbackFileIdentifier(R.raw.qonversion_android_fallbacks)
    .build();
  ```
</CodeGroup>

#### React Native / Cordova / Flutter

Place the fallback file in the project directory for both iOS and Android platforms, and Qonversion **will handle the rest by automatically** fetching and using it. For Android use `main/assets` directory.

#### Unity

Place both `qonversion_ios_fallbacks.json` and `qonversion_android_fallbacks.json` files into the `Assets/StreamingAssets` directory. This ensures the fallback files are included in both iOS and Android platform projects during the export process. Qonversion **will then automatically retrieve and utilize these files.**

#### Availability

Please note that fallback files are supported only for the SDKs starting from the following versions:

| SDK          | Version |
| ------------ | ------- |
| iOS          | 5.11.0  |
| Android      | 8.0.0   |
| React-Native | 8.0.0   |
| Flutter      | 9.0.0   |
| Unity        | 8.0.0   |
| Cordova      | 6.0.0   |
| Capacitor    | 0.1.0   |

### How to test?

Call the following function to ensure the fallback file is placed into the correct directory and can be successfully fetched and mapped by Qonversion SDK.

Use this function only during development, and make sure to remove it before the final release. Using it in production will not harm the product, but it is unnecessary code.

<CodeGroup>
  ```swift Swift theme={null}
  let isFallbackFileAccessible = Qonversion.shared.isFallbackFileAccessible()
  ```

  ```objectivec Objective-C theme={null}
  BOOL isFallbackFileAccessible = [[Qonversion sharedInstance] isFallbackFileAccessible];
  ```

  ```kotlin Kotlin theme={null}
  val isFallbackFileAccessible = Qonversion.shared.isFallbackFileAccessible()
  ```

  ```java Java theme={null}
  Boolean isFallbackFileAccessible = Qonversion.getSharedInstance().isFallbackFileAccessible();
  ```

  ```dart Flutter theme={null}
  bool isFallbackFileAccessible = await Qonversion.getSharedInstance().isFallbackFileAccessible();
  ```

  ```typescript React Native theme={null}
  const isFallbackFileAccessible = await Qonversion.getSharedInstance().isFallbackFileAccessible();
  ```

  ```csharp Unity theme={null}
  bool isFallbackFileAccessible = Qonversion.GetSharedInstance().IsFallbackFileAccessible();
  ```

  ```typescript Cordova theme={null}
  const isFallbackFileAccessible = await Qonversion.getSharedInstance().isFallbackFileAccessible();
  ```

  ```typescript Capacitor theme={null}
  const isFallbackFileAccessible = await Qonversion.getSharedInstance().isFallbackFileAccessible();
  ```
</CodeGroup>

***

[How Qonversion Works](how-qonversion-works)

[Quick Start](quickstart)


# Tenjin
Source: https://documentation.qonversion.io/docs/tenjin

Send iOS and Android in-app subscription and purchase events to Tenjin with Qonversion.

Measure what drives your in-app subscription revenue on the ad campaign level by tracking events like trial-to-paying-user conversions, subscription renewals, refunds, upgrades, and other valuable events in Tenjin. Qonversion tracks revenue even if a user does not open your app. This allows for measuring the cohorts' revenue with 100% accuracy.

## 1. Provide Integration Details

1. Before sending events to Tenjin, ensure you've added your apps to the Tenjin dashboard. Then get your **Tenjin API key** from the dashboard.

<Frame>
  <img />
</Frame>

2. Navigate to the Integrations section in your Qonversion project, select [Tenjin](https://dash.qonversion.io/app/integration/tenjin), and provide the **Tenjin API key** and Save.

3. For an iOS app, you should add Bundle ID. For Android App you need to provide the Tenjin API Key only.

<Frame>
  <img />
</Frame>

## 2. Setup the SDKs

1. Make sure you have Tenjin SDK installed. Check the official Tenjin SDK documentation [here](https://github.com/tenjin)
2. Set Qonversion SDK following [Installing the SDKs](install-sdk) guides.
3. Send Tenjin `analytics_installation_id` to Qonversion via [User Properties](user-properties)

<CodeGroup>
  ```swift Swift theme={null}
  let tenjinId = TenjinSDK.getAnalyticsInstallationId()
  Qonversion.shared().setUserProperty(.tenjinAnalyticsInstallationId, value: tenjinId)
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyTenjinAnalyticsInstallationId value:[TenjinSDK getAnalyticsInstallationId]];
  ```

  ```java Java theme={null}
  TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
  String analyticsId = instance.getAnalyticsInstallationId();

  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.TenjinAnalyticsInstallationId, analyticsId);
  ```

  ```kotlin Kotlin theme={null}
  val instance = TenjinSDK.getInstance(this, "<SDK_KEY>")
  val analyticsId = instance.analyticsInstallationId

  Qonversion.shared.setUserProperty(QUserPropertyKey.TenjinAnalyticsInstallationId, analyticsId)
  ```

  ```dart Flutter theme={null}
  String? analyticsId = await TenjinSDK.instance.getAnalyticsInstallationId();

  if (analyticsId != null) {
      Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.tenjinAnalyticsInstallationId, analyticsId);
  }
  ```

  ```typescript React Native theme={null}
  const analyticsId = await Tenjin.getAnalyticsInstallationId()

  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.TENJIN_ANALYTICS_INSTALLATION_ID, analyticsId);
  ```

  ```csharp Unity theme={null}
  BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
  analyticsId = instance.GetAnalyticsInstallationId;

  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.TenjinAnalyticsInstallationId, analyticsId);
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.TENJIN_ANALYTICS_INSTALLATION_ID, "tenjinAiid");
  ```

  ```typescript Capacitor theme={null}
  const analyticsId = await Tenjin.getAnalyticsInstallationId();

  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.TENJIN_ANALYTICS_INSTALLATION_ID, analyticsId);
  ```
</CodeGroup>

<Warning>
  ### Switch off the toggle "Send sales as proceed"

  Tenjin automatically subtracts App Stores commission, so you need to send gross sales data to Tenjin.
</Warning>

<Check>
  ### Done

  Now Qonversion will start sending in-app purchases and subscriptions data to your Tenjin account.
</Check>

## Event names

You can configure some of the event names for this integration. Purchase events with revenue value (like Trial Converted or Subscription Started) do not have names in Tenjin, so they all have the same default **Purchase** name in Qonversion.

## Event Payload

In case you need details about data sent to Tenjin, follow the example below:

<CodeGroup>
  ```json theme={null}
  {
    "advertising_id": "",
    "analytics_installation_id": "",
    "developer_device_id": "",
    "bundle_id": "",
    "platform": "",
    "sdk_version": "",
    "os_version": "",
    "os_version_release": "",
    "limit_ad_tracking": "",
    "api_key": "",
    "ip_address": "",
    "country": "",
    "app_version": "",
    "product_id": "",
    "price": "",
    "quantity": "",
    "currency": ""
  }
  ```
</CodeGroup>

***

[Slack](slack)

[Webhooks](webhooks)


# Test Purchases — Apple
Source: https://documentation.qonversion.io/docs/test-purchase-apple

Verify your Apple App Store integration end to end with a sandbox tester account and a test purchase reported to Qonversion.

Follow the steps below to verify your Apple App Store integration with a sandbox test purchase.

## 1. Set Up a Sandbox Test Account

1. Go to [App Store Connect](https://appstoreconnect.apple.com/) -> **Users and Access** -> **Sandbox** -> **Testers**.
2. Create a new sandbox tester account or use an existing one.

## 2. Configure Sandbox Environment

Add the sandbox environment setting to your SDK initialization to distinguish test data from production:

```swift Swift theme={null}
let config = Qonversion.Configuration(projectKey: "[projectKey]", launchMode: .subscriptionManagement)
config.setEnvironment(.sandbox) // Add this line for testing
Qonversion.initWithConfig(config)
```

```objectivec Objective-C theme={null}
QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"[projectKey]" launchMode:QONLaunchModeSubscriptionManagement];
[configuration setEnvironment:QONEnvironmentSandbox]; // Add this line for testing
[Qonversion initWithConfig:configuration];
```

<Warning>
  Make sure to use a physical device (not a simulator) when testing iOS purchases.
</Warning>

## 3. Make a Test Purchase

1. Run your app on a physical device.
2. Sign in with the sandbox tester account on the device (**Settings** -> **App Store** -> **Sandbox Account**).
3. Trigger a purchase in your app — the App Store will process it in sandbox mode.

<Warning>
  Do not use the sandbox environment in production. Switch to the production environment before releasing your app.
</Warning>


# Test Purchases — Google Play
Source: https://documentation.qonversion.io/docs/test-purchase-google

Verify your Google Play integration with a license-tester test purchase and confirm the transaction reaches your Qonversion dashboard.

Follow the steps below to verify your Google Play integration with a test purchase.

## 1. Set Up License Testing

1. Go to [Google Play Console](https://play.google.com/console/) -> **Settings** -> **License testing**.
2. Add the Gmail account you will use for testing.
3. Set the license response to **RESPOND\_NORMALLY**.

## 2. Set Up a Test Device

You can use a physical device or an emulator with Google Play Store installed.

For emulators, make sure to select an image with **Google Play Store** support in Android Studio's AVD Manager.

The test Gmail account must be the **primary account** on the device.

## 3. Configure Sandbox Environment

Add the sandbox environment setting to your SDK initialization to distinguish test data from production:

```kotlin Kotlin theme={null}
val qonversionConfig = QonversionConfig.Builder(
    this,
    "[projectKey]",
    QLaunchMode.SubscriptionManagement
)
    .setEnvironment(QEnvironment.Sandbox) // Add this line for testing
    .build()
Qonversion.initialize(qonversionConfig)
```

```java Java theme={null}
final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
        this,
        "[projectKey]",
        QLaunchMode.SubscriptionManagement
)
        .setEnvironment(QEnvironment.Sandbox) // Add this line for testing
        .build();
Qonversion.initialize(qonversionConfig);
```

## 4. Make a Test Purchase

1. Run your app on the test device.
2. Sign in with the license tester Gmail account.
3. Trigger a purchase — Google Play will process it in test mode.

<Warning>
  If you see "Something went wrong" during the first purchase, go to **Settings -> Accounts** on the device and complete the account sign-in process.
</Warning>

<Warning>
  Do not use the sandbox environment in production. Switch to the production environment before releasing your app.
</Warning>


# Test Purchases — Paddle
Source: https://documentation.qonversion.io/docs/test-purchase-paddle

Verify your Paddle integration with a sandbox test purchase — Paddle keeps Production and Sandbox fully separate, so testing runs against the Paddle sandbox environment.

Follow the steps below to verify your Paddle integration with a test purchase. Paddle keeps **Production** and **Sandbox** in fully separate environments, so all testing happens against the Paddle sandbox.

## 1. Connect Paddle Sandbox to Qonversion

Paddle sandbox testing in Qonversion uses a separate sandbox connection that is independent from your live Paddle connection. The two environments have separate API keys.

1. If you don't have a Paddle sandbox account yet, [sign up here](https://sandbox-login.paddle.com/signup).
2. Generate a **Sandbox** API key in the [Paddle sandbox Developer Tools](https://sandbox-vendors.paddle.com/authentication-v2). Sandbox keys start with `pdl_sdbx_`.
3. In Qonversion, open **Project Settings → Stores** and find the **Paddle** card.
4. Click **Configure Paddle**, paste your sandbox API key into the **Sandbox → API Key** field, and click **Connect Sandbox**. See [Paddle Credentials](paddle-credentials) for details.

<Info>
  When you connect the sandbox key, Qonversion registers the webhook destination on your Paddle sandbox account automatically. You can confirm everything is wired up with the **Test Connection** and **Test Webhook** buttons in the Paddle drawer.
</Info>

Once connected, click the **Sandbox mode** icon in the top bar of the Qonversion dashboard to view your test data.

## 2. Use the Paddle Sandbox

1. Make sure you are working in the [Paddle sandbox dashboard](https://sandbox-vendors.paddle.com) and that your checkout points at the sandbox API (`https://sandbox-api.paddle.com`).
2. All transactions made in the sandbox are isolated from your live Paddle account and cannot process real charges.

## 3. Make a Test Purchase

Open your Paddle Checkout (running against the sandbox). Tag it with your Qonversion User ID in `custom_data` (the `qonversion_client_uid` key) so the purchase maps to a user, exactly as in production — see [Send Paddle Purchases to Qonversion](initiate-purchase-paddle). Then complete a payment using Paddle's test card:

| Card Number           | Description              |
| :-------------------- | :----------------------- |
| `4111 1111 1111 1111` | Successful payment       |
| `4000 0038 0000 0446` | 3D Secure authentication |
| `4000 0000 0000 0002` | Declined payment         |

Use any future expiration date, CVC `100`, and any name. (Any 3-digit CVC works, but Paddle's sandbox documents `100`.) `4111 1111 1111 1111` is the card Paddle's sandbox checkout form itself suggests.

With `custom_data` set, Qonversion maps the sandbox purchase to your user from the Paddle webhook automatically — confirm the test transaction appears in your Qonversion sandbox data. (If you submit purchases explicitly instead, send it to Qonversion as described in [Send Paddle Purchases to Qonversion](initiate-purchase-paddle).)

<Warning>
  Make sure to connect your production Paddle API key and switch to production before going live.
</Warning>


# Test Purchases — Stripe
Source: https://documentation.qonversion.io/docs/test-purchase-stripe

Verify your Stripe integration with a test-mode purchase using Stripe test cards and confirm it reaches your Qonversion dashboard.

Follow the steps below to verify your Stripe integration with a test purchase.

## 1. Connect Stripe Sandbox to Qonversion

Stripe testing in Qonversion uses a separate sandbox connection that is independent from your live Stripe connection. This is required by Stripe Connect, which keeps live and sandbox connected accounts in isolated environments ([Stripe docs](https://docs.stripe.com/sandboxes)).

1. In your [Stripe Dashboard](https://dashboard.stripe.com/), toggle **Test mode** (top-right).
2. In Qonversion, open **Project Settings -> Stores** and find the **Stripe** card.
3. Click **Connect Sandbox** on the Stripe card. You will be redirected to Stripe's OAuth flow.
4. In the Stripe account picker, select the existing sandbox connected account (often labelled "Unnamed account" with a recent creation date) and click **Connect**.

<Info>
  Stripe provisions a separate sandbox connected account during the OAuth flow. This is expected and is how Stripe Connect isolates test environments. The sandbox account lives under your existing Stripe login, cannot process real charges, and has no billing impact. It is not a duplicate of your live business account, and you can rename it in Stripe (for example "Acme Sandbox") to make it easier to recognise later.
</Info>

Once connected, click the **Sandbox mode** icon in the top bar of the Qonversion dashboard to view your test data.

## 2. Enable Stripe Test Mode

1. Go to [Stripe Dashboard](https://dashboard.stripe.com/).
2. Toggle **Test mode** in the top-right corner.
3. All transactions made in test mode will use Stripe's sandbox environment.

## 3. Make a Test Purchase

Use one of [Stripe's test card numbers](https://docs.stripe.com/testing#cards) to simulate a payment:

| Card Number           | Description              |
| :-------------------- | :----------------------- |
| `4242 4242 4242 4242` | Successful payment       |
| `4000 0000 0000 3220` | 3D Secure authentication |
| `4000 0000 0000 0002` | Declined payment         |

Use any future expiration date and any 3-digit CVC.

<Warning>
  Make sure to switch to production Stripe API keys before going live.
</Warning>


# Overview
Source: https://documentation.qonversion.io/docs/testing

Test in-app purchases and subscriptions after implementing Qonversion SDKs

## 1. View Test Data

You can see the test data in Qonversion by switching the *Sandbox mode* toggle on the right side at the top in [Qonversion Dashboard](https://dash.qonversion.io/) . While using this mode, you will see the Test Mode label at the top of all the dashboards. Remember to switch it off when you have finished testing.

<Warning>
  Make sure to use a device (not a simulator) when testing iOS purchases.
</Warning>

<Frame>
  <img />
</Frame>

With Qonversion SDK initialization, you can set the environment to distinguish sandbox and production users.

<CodeGroup>
  ```swift Swift theme={null}
  let config = Qonversion.Configuration(projectKey: "projectKey", launchMode: .subscriptionManagement)
  config.setEnvironment(.sandbox)
  Qonversion.initWithConfig(config)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"projectKey" launchMode:QONLaunchModeSubscriptionManagement];
  [configuration setEnvironment:QONEnvironmentSandbox];
  [Qonversion initWithConfig:configuration];
  ```

  ```java Java theme={null}
  final QonversionConfig qonversionConfig = new QonversionConfig.Builder(
          this,
          "projectKey",
          QLaunchMode.SubscriptionManagement
  )
          .setEnvironment(QEnvironment.Sandbox)
          .build();
  Qonversion.initialize(qonversionConfig);
  ```

  ```kotlin Kotlin theme={null}
  val qonversionConfig = QonversionConfig.Builder(
      this,
      "projectKey",
      QLaunchMode.SubscriptionManagement
  )
      .setEnvironment(QEnvironment.Sandbox)
      .build()
  Qonversion.initialize(qonversionConfig)
  ```

  ```dart Flutter theme={null}
  final config = new QonversionConfigBuilder(
      'projectKey',
      QLaunchMode.subscriptionManagement
  )
      .setEnvironment(QEnvironment.sandbox)
      .build();
  Qonversion.initialize(config);
  ```

  ```typescript React Native theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEnvironment(Environment.SANDBOX)
    .build();
  Qonversion.initialize(config);
  ```

  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      )
      .SetEnvironment(Environment.Sandbox)
      .Build();
  Qonversion.Initialize(config);
  ```

  ```typescript Cordova theme={null}
  const config = new Qonversion.ConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEnvironment(Qonversion.Environment.SANDBOX)
    .build();
  Qonversion.initialize(config);
  ```

  ```typescript Capacitor theme={null}
  const config = new QonversionConfigBuilder(
    'projectKey',
    LaunchMode.SUBSCRIPTION_MANAGEMENT
  )
    .setEnvironment(Environment.SANDBOX)
    .build();
  Qonversion.initialize(config);
  ```
</CodeGroup>

<Warning>
  Do not use the sandbox environment in production. Set the production environment before releasing your app to an app store.
</Warning>

Please note that sandbox subscriptions renew at an accelerated rate and will auto-renew 6-9 times before the user is unsubscribed. This lets you test how your app handles subscription renewal and expiration states.

| Subscription Duration | Apple Test Subscription Renewal | Google Test Subscription Renewal |
| --------------------- | ------------------------------- | -------------------------------- |
| 1 week                | 3 minutes                       | 5 minutes                        |
| 1 month               | 5 minutes                       | 5 minutes                        |
| 2 months              | 10 minutes                      | –                                |
| 3 months              | 15 minutes                      | 10 minutes                       |
| 6 months              | 30 minutes                      | 15 minutes                       |
| 1 year                | 1 hour                          | 30 minutes                       |

## 2. Send Test Events to the Integrations

You can test an integration by sending test events to it. Navigate to the integration you want to test and switch on the *Send sandbox events* toggle. Remember to turn it off once you have completed the testing to avoid having mixed sandbox & production data in your integration.

## 3. How Sandbox and Production Data Are Organized

When you toggle Sandbox mode in the dashboard, only some of the data you see switches with it. Understanding how each object is scoped helps avoid surprises while testing:

| Object                                                                 | Scope                                                            |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Qonversion ID (identifier)                                             | Findable from either environment; the same ID exists in both     |
| Products, Entitlement definitions                                      | Project-wide; configured once and visible in both environments   |
| Entitlement grants, Subscriptions, Purchases, Events, Devices, Revenue | Environment-scoped; tracked separately in sandbox and production |

A single Qonversion ID can therefore have separate sandbox and production records underneath. The user-level identifier is shared, but the per-environment data (entitlement grants, subscriptions, events, devices) is recorded against the environment the user was active in.

A few practical consequences:

* **Customers list**: Built from transaction events (trials, subscriptions, one-time purchases, renewals). A newly created user with no events does not appear in the list until they trigger their first event. Use the customer search to look up such users directly.
* **Customer search**: Finds users by exact Qonversion ID, identity, or email regardless of the Sandbox/Production toggle, because the Qonversion ID is unique per project across environments.
* **Customer Profile**: The Qonversion ID and identity stay the same as you toggle, but the subscription widget, customer history, and entitlement grants reload from the environment selected by the **Sandbox mode** icon in the top bar.

## 4. Testing Checklist

☑️ Make sure you can see test trials and subscriptions on your Qonversion Dashboard.

If you see the test subscriptions, your integration with the subscription provider (App Store, Google Play, Stripe) is correct. Qonversion adds purchases to dashboards after validating them with Apple, Google, or Stripe. If you can't see any test subscriptions with *Sandbox mode* turned on after making a purchase, check the App-Specific Shared Secret for the iOS app, Service Account Key for the Android App, or Stripe Sandbox your [project settings](https://dash.qonversion.io/project/stores).

☑️ Check your test events have been delivered to your integrations.

Make sure to turn on the *Send sandbox events* toggle in the integrations you want to test before purchasing. You can see the last events sent to active integration in the [Events Dashboard ](https://dash.qonversion.io/events)on the left side menu. You can see the status of each event by clicking on it. Make sure that the event was delivered. In case you see an error message, check your integration settings.

***

[Users and Access](users-and-access)

[Troubleshooting](troubleshooting)


# Restore behavior
Source: https://documentation.qonversion.io/docs/transferring

Two available behaviors exist for reassigning the same subscription to different users:

* Transfer entitlement: Entitlement is to be transferred to another Identity user on restore.
* Copy entitlement: Entitlement is to be copied to another Identity user on restore.

For configuring this feature, navigate to the [entitlements settings section](https://dash.qonversion.io/entitlements/transferring).

<img alt="" />

***

[User Identifiers](user-identifiers)

[Google Play Product Details](google-play-product-details)


# Trials
Source: https://documentation.qonversion.io/docs/trials

Qonversion provides in-depth analytics of your in-app trial offers

## Available Charts

### Active Trials

The Active Trials chart shows the active trial subscriptions for the selected dates. The chart also shows the segmentation of active trials by their auto-renew state. The chart's title shows your active trials at the end of the selected period; the percentage shows how this number changed during the period chosen. In the example below, for the 30th of June, you have 461 active trial subscriptions, which is 18.23% higher than you had for the 1st of June.

<Frame>
  <img />
</Frame>

### New Trials

The number of trial start events for the period chosen

<Frame>
  <img />
</Frame>

### Trials Movement

The Trials Movement chart helps you understand how your trial subscriptions base changes over time. This chart includes the increase in the trial subscriptions (above zero; trial started events) and trials expired (below zero; trial expired events).

When a user cancels a trial, it means that a user turns off auto-renewal. This trial is still active (the user has access to premium features) till the trial expiration date.

The chart's title shows the net number of trial subscriptions during the selected period; the percentage shows how this value changed compared to the previous period of the same length. In the example below, from the 1st of June until the 30th of June, your trial subscription base had increased by 2,332 trial subscriptions, which is 1.66% higher than your growth in the previous period of the same length (30 days).

<Frame>
  <img />
</Frame>

### Trial-to-Paid Conversion

Trials conversion rate is calculated as the ratio of: → Numerator: Trial converted events attributed to trial start date → Denominator: Trial started events for the period chosen For example, 10 trial start events occurred on January 1st. The duration of the trial is 7 days. 2 trials were converted on January 8th, and the rest of the trials were cancelled. The trial conversion rate for January 1st equals 2/10 = 20%. Please note that the chart will show a 0% conversion rate for the most recent 3-7 days as trials for the most recent days have not converted yet. As soon as the conversion happens, the chart is updated with the conversion value.

<Frame>
  <img />
</Frame>

### Trials Cancellation Rate

Trials cancellation rate is calculated as the ratio of: → Numerator: Trial cancelled events attributed to trial start date → Denominator: Trial started events for the selected period

<Frame>
  <img />
</Frame>

***

[New users](users)

[Subscriptions](subscriptions)


# Troubleshooting
Source: https://documentation.qonversion.io/docs/troubleshooting

Solutions to common Qonversion SDK and dashboard errors: product-not-found, receipt validation, store credentials, StoreDetails, billing, and Google RTDN issues.

<img alt="" />

Check out our troubleshooting guide for quick solutions to common problems. If you went through this guide and you're still having problems, reach out to us on [GitHub](https://github.com/qonversion) or open an issue on the relevant SDK repository - [iOS](https://github.com/qonversion/qonversion-ios-sdk/issues), [Android](https://github.com/qonversion/android-sdk/issues), [React Native](https://github.com/qonversion/react-native-sdk/issues), [Flutter](https://github.com/qonversion/flutter-sdk/issues), [Cordova](https://github.com/qonversion/cordova-plugin/issues), [Capacitor](https://github.com/qonversion/capacitor-plugin/issues), or [Unity](https://github.com/qonversion/unity-sdk/issues).

<Info>
  ### Update Qonversion SDK to the latest version

  We recommend updating your Qonversion SDK to the latest version. It brings new features, improvements, and bug fixes for optimal performance. Refer to the updated [Installing the SDKs](install-sdk) documentation for step-by-step instructions on how to seamlessly integrate the latest SDK version into your app.
</Info>

## All stores

These errors are not specific to a single store and can occur on iOS, Android, or the web.

<AccordionGroup>
  <Accordion title="Active store not found">
    There are no active stores in the settings of your project. This is the `QONErrorCodeProjectConfigError` (32) / `ProjectConfigError` error.

    To fix the error, do the following:

    1. Open the project settings and select the `Stores` tab.
    2. [Activate and set up](quickstart#2-create-a-project-and-register-your-app) the required store.

       <img alt="" />
  </Accordion>

  <Accordion title="Invalid access token received">
    Make sure that you set the correct [Project Key](quickstart#2-create-a-project-and-register-your-app) to the `Qonversion Configuration Builder`. The project key is found in the [project Settings](https://dash.qonversion.io/project/settings); it is not the same as a store shared secret or service account key.
  </Accordion>

  <Accordion title="Invalid Store Credentials Error">
    This is the `QONErrorCodeInvalidStoreCredentials` (33) / `InvalidStoreCredentials` error. Fix it per platform:

    **iOS**

    * Please make sure to provide the correct [Shared Secret](ios-app-store-info-fields#2-generate-the-app-specific-shared-secret) in the Qonversion Dashboard.
    * Please make sure to fill out the tax information and agreement for the paid apps section.

    **Android**

    * [Check](https://play.google.com/console/developers/users-and-permissions) that your service account registered in the Google Play Console has the necessary account entitlements for Qonversion: **View financial data** and **Manage orders and subscriptions**.
    * Make some updates in your product's configuration in Google Play Console. For example, edit the product description and save it. It will update Google's cache.
  </Accordion>

  <Accordion title="Product not found error (ProductNotFound)">
    This is the `QONErrorCodeProductNotFound` (2) / `ProductNotFound` error. Here are the most frequent reasons for receiving a **product not found** error.

    **All stores**

    * You are trying to buy a product with the wrong Qonversion Product ID, or you have not set the product identifiers in the [Qonversion dashboard](create-products).
    * You are trying to buy a product with the wrong Google Play Store ID + base plan ID or App Store Product ID configured on the [Qonversion dashboard](create-products).

    **App Store only**

    1. Products need to be in **Ready to submit** or **Ready for sale** status. How to navigate: App Store Connect, select your app, click **Manage** under the In-App Purchases title on the left menu.
    2. Your payment and tax agreements in Apple Developer Account should be filled in.
    3. Apple StoreKit returns `invalidProductIdentifiers` and an empty products response.
  </Accordion>

  <Accordion title="Missing entitlements after purchase">
    In case you are receiving empty or unexpected entitlement data:

    1. Ensure that products and entitlements are configured correctly in the [Qonversion dashboard](entitlements). Check if the purchased product is linked to the expected entitlement.
    2. `iOS Only` Make sure you are not using a `.storekit` file. Products from the `.storekit` file are available only on your local phone or simulator. They are unavailable on App Store Connect and can't be validated.
    3. `Android Only` If [in-app products](android-in-app-products) are created **before** [granting users access](android-store-setup#6-grant-the-service-account-access-in-google-play-console) or [enabling the required Google Cloud APIs](android-store-setup#2-enable-the-required-google-apis) for the service account, it may cause problems with the receipt validation using Google Play Developer API. Google Play Developer API can return the following error: *"The current user has insufficient permissions to perform the requested operation."* When encountering this issue, open the In-app products or Subscription tab respectively on the Google Play Console and make some updates. For example, edit the product description and save it.
  </Accordion>
</AccordionGroup>

## iOS only

These errors occur only on iOS / App Store Connect.

<AccordionGroup>
  <Accordion title="Invalid store product identifiers">
    Apple StoreKit returns `invalidProductIdentifiers` and an empty products response. In this case, you will see this error in the log:

    `❌ Invalid store products identifiers: ("some_product_identifier", "some_other_product_identifier")`

    There are a few reasons why this error can occur:

    1. Your in-app purchases are not configured correctly on App Store Connect. Check the first point of this section.
    2. Your app bundle ID does not match the bundle ID from App Store Connect where purchases were created.
    3. You are using a `.storekit` file which is configured with other IDs than you are trying to use.
    4. You have unfilled payment and tax agreements in your Developer Account.
    5. Unknown StoreKit issue. In some cases, StoreKit returns invalid store product identifiers without any visible reason. Update the product title in App Store Connect, wait about 15-30 min, and try to request products in the Qonversion SDK again.
  </Accordion>

  <Accordion title="Receipt validation error">
    Here are the most frequent reasons for the SDK `QONErrorCodeReceiptValidationError` (34):

    * Provided shared secret can't be used for validation. Please make sure the shared secret you set in the [Qonversion settings dashboard](https://dash.qonversion.io/project/stores) is correct.
    * The receipt is corrupted.
    * The receipt was not found on the Apple server.
    * Apple Receipt Validation service is temporarily unavailable.
  </Accordion>

  <Accordion title="Operation couldn't be completed with error: 2">
    * In case you're receiving such an error, make sure that you configured the `App Store Bundle ID` at the [Store Settings](https://dash.qonversion.io/project/stores) tab correctly.
    * Use a device (not a simulator) when testing iOS purchases.
  </Accordion>

  <Accordion title="Purchase result without dialog window open">
    In most cases, it happens because of unfinished transactions. If this issue occurs many times in a row, the possible reason is that some transactions can't be finished. Please ensure you didn't delete some App Store products that were purchased on the current Sandbox account. Create a new sandbox account and test again.
  </Accordion>
</AccordionGroup>

## Android only

These errors occur only on Android / Google Play.

<AccordionGroup>
  <Accordion title="Empty StoreDetails (or SkuDetails) error">
    Here are the most frequent reasons for the **StoreDetails** (or **SkuDetails**) error.

    1. Your in-app products are not configured correctly in Google Play Console. Once you have created a product, it has an Inactive status. You have to **activate the product** to purchase it. For more details, see our [Android In-App Products Setup](android-in-app-products) guide.
    2. Your app has an **application ID different from the original APK uploaded to Google Play Console**. An **applicationIdSuffix** for the debug **buildType** in the build.gradle file may also cause an error. When you use applicationIdSuffix you actually change your applicationId. As a result, Google Play Store treats your app as a completely different app.
    3. It could be a problem on the Google side, so we recommend updating the in-app purchase information in the Google Play Console. You can update the in-app purchase description and save it.
    4. In case you don't see the changes applied, please try to clear the Google Play Store cache on your test device.
  </Accordion>

  <Accordion title="Billing Unavailable error">
    The Billing service is unavailable on the device because it is not connected to any Google account at the moment. This is the `BillingUnavailable` error. Here are the possible reasons:

    1. You are testing on an emulator. Please make sure that the emulator has the Play Store installed.
    2. You are not logged into a test device with a Google account.

    For more details see [Android test devices](android-test-devices).
  </Accordion>

  <Accordion title="The purchase token does not match the package name">
    Ensure that you've inserted your package name correctly in the [Store Settings](https://dash.qonversion.io/project/stores) tab. You can find `applicationID` in your app-level `build.gradle` file.
  </Accordion>

  <Accordion title="Product Unavailable error: The item you requested is not available for purchase">
    Please make sure that you checked the solutions below:

    1. The app's publish mode on the Google Play Console is **Published**. It should not be **Draft**.
    2. The uploaded App Bundle or APK file matches the one you are testing, including the following parameters: **versionCode**, **versionName**, **applicationId**, and **keystore signature**.
    3. You are not using your developer Google account while testing purchases.
    4. You have created a test account in the developer console.
    5. You have configured the test account as follows:
       * You are signed in on your device with your test account.
       * For closed alpha/beta testing, you added your test account to the selected testers group. You have been approved to become a tester and accepted participation in the internal app testing via an invite link.
    6. Clear the cache data of the Google Play App. If the error persists, then log out and log in to your Google account on the device.
  </Accordion>

  <Accordion title="Purchase Invalid: Proxy of the BillingClient DEVELOPER_ERROR">
    Check the following steps to resolve this error:

    * Ensure that the uploaded App Bundle or APK file on the Google Play Console matches the one you are testing, including the following parameters: versionCode, version name, applicationId, and keystore signature.
    * Make sure that you are not using your developer Google account while testing purchases.
    * Clear the cache data of the Google Play App. If the error persists, then log out and log in to your Google account on the device.

    You can check the details on DEVELOPER\_ERROR in the Google developer documentation [here](https://developer.android.com/reference/com/android/billingclient/api/BillingClient.BillingResponseCode#developer_error).
  </Accordion>

  <Accordion title="Google RTDN is not working or fails to connect">
    Check the following:

    1. **Incorrect Pub/Sub topic format in Google Play Console.** You must set the topic in this exact format: `projects/YOUR_PROJECT_ID/topics/YOUR_TOPIC_NAME`.

    2. **Missing IAM permission for Google's RTDN publisher.** Google's RTDN system must have permission to publish to your topic. Run this:

       ```bash theme={null}
       gcloud pubsub topics add-iam-policy-binding your-topic \
         --member="serviceAccount:google-play-developer-notifications@system.gserviceaccount.com" \
         --role="roles/pubsub.publisher"
       ```

       If not set, no events will be delivered, and no error will be shown.

    3. **Pub/Sub topic exists in the wrong GCP project.** Ensure your topic is in the same Google Cloud project that your Play Console uses. Check your active project:

       ```bash theme={null}
       gcloud config get-value project
       ```

       Google Play references topics by project ID, not number or display name.

    4. **GCP billing is disabled or suspended.** Even if Pub/Sub is free-tier, the project must have billing enabled. Go to [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) and verify that your billing account is active and linked to the correct project.

    5. **Domain restricted sharing organization policy.** The issue can be with the "Domain restricted sharing" organization policy in Google Cloud. It might be automatically set to a strict rule. You need to set that to "Google Managed Default."

    6. **Topic not properly saved in Google Play Console.** Sometimes saving the topic in Monetization setup silently fails. Steps:
       1. Go to Monetization > Monetization setup.
       2. Check the RTDN section.
       3. Ensure the topic is still present after saving.
       4. If not, re-enter and save again.

    7. **No qualifying events triggered yet.** RTDN only sends events for subscription purchases, renewals, cancellations, grace period changes, pauses, etc.

    8. **App not published or package name mismatch.** If the app is in draft, not yet released to internal testing, or has a different `packageName` than what's configured in Google Play, RTDN will not activate. Push your app to internal or closed testing, and verify your `packageName` matches exactly.

    9. **Domain Restricted Sharing policy is enabled.** This policy is enabled by default; adding the domain associated with the user may not work. Remove this policy.

    10. **No active Pub/Sub subscription or message retention.** Pub/Sub by default drops messages if no subscription exists. You need to either create a subscription:

        ```bash theme={null}
        gcloud pubsub subscriptions create your-sub \
          --topic=your-topic
        ```

        Or enable message retention explicitly on the topic.
  </Accordion>

  <Accordion title="Android: setProperty does not work">
    **Why it happens:** an issue with the Hilt library.

    **Solution:** add this to the Android manifest:

    ```xml theme={null}
    <provider android:name="androidx.startup.InitializationProvider" android:authorities="${applicationId}.androidx-startup" android:exported="false" tools:node="merge">

    <meta-data android:name="androidx.work.WorkManagerInitializer" android:value="androidx.startup" tools:node="remove">

    </provider>
    ```

    Read more: [https://github.com/qonversion/android-sdk/issues/549](https://github.com/qonversion/android-sdk/issues/549)
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Sandbox testing" icon="flask" href="testing">
    Set up sandbox accounts and test devices for iOS and Android before going live.
  </Card>

  <Card title="Qonversion SDK error codes" icon="triangle-exclamation" href="handling-errors">
    Full reference of `QONErrorCode` values and their meaning across platforms.
  </Card>
</CardGroup>


# Troubleshooting - Active store not found
Source: https://documentation.qonversion.io/docs/troubleshooting-active-store-not-found



We received your purchase for the store, which needed configuring during the previous steps. Please, return to the *Connect Stores* section and check whether you filled in all the required fields for the store chosen.


# Troubleshooting - Invalid access token received
Source: https://documentation.qonversion.io/docs/troubleshooting-invalid-access-token-received



In the *Analytics Mode* section, we have inserted *Project Key* to the Qonversion Configuration Builder. Please ensure you applied the code provided without changes in the object's builder.


# Troubleshooting - Invalid Store Credentials Error
Source: https://documentation.qonversion.io/docs/troubleshooting-invalid-store-credentials-error

Fix invalid store credentials errors by verifying your iOS shared secret and Android service account permissions in Google Play Console.

## IOS

Please return to the *Connect Stores* step and ensure you have provided the correct <a href="/docs/ios-app-store-info-fields#2-generate-the-app-specific-shared-secret">Shared Secret</a>

## Android

Check in the <a href="https://play.google.com/console/developers/users-and-permissions">Google Play Console</a> that the provided service account was granted with the following permissions:

* View financial data
* Manage orders and subscriptions


# Tutorials
Source: https://documentation.qonversion.io/docs/tutorials

Watch video tutorials for implementing in-app purchases and subscriptions with Qonversion on iOS, Android, Flutter, and more.

## Video Tutorials

### 1. iOS In-App Purchases & Subscription management with Qonversion - Rebeloper Tutorial

<iframe />

### 2. Implement iOS in-app subscriptions with Qonversion - iOS Academy Tutorial

<iframe />

### 3. Implement Subscriptions & In-App Purchases in Android with Qonversion - Philipp Lackner Tutorial

<iframe />

### 4. In-App Subscription and Payment of Digital Goods with Qonversion - Flutter Explained Tutorial

<iframe />

***

[Sample Apps](sample-apps)

[Deferred Purchases](deferred-purchases)


# Unity 4.+ migration guide
Source: https://documentation.qonversion.io/docs/unity-4-migration-guide

Historical migration guide for upgrading the Qonversion Unity SDK to major version 4.+: updated initialization, renamed methods, and revised purchase and entitlement APIs.

## Upgrading version

Increase the dependency version in your Packages/manifest.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json manifest.json theme={null}
  "com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#4.0.0"
  ```
</CodeGroup>

## Initialization

Qonversion Unity SDK 4 contains significant changes in how the library is initialized. We are moving from a static class approach to an instance-based one. Before, you initialized Qonversion using the `Launch` call:

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.Launch("projectKey", true);
  ```
</CodeGroup>

Now, instead, you should create a `QonversionConfig` object using `QonversionConfigBuilder` and provide it to the initialization method as follows:

<CodeGroup>
  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      ).Build();
  Qonversion.Initialize(config);
  ```
</CodeGroup>

Note that instead of providing the `observeMode` flag to the `Launch` call, you now should provide a concrete value from the `LaunchMode` enum depending on which mode you use Qonversion. Also, we've renamed our modes to make them more transparent for users:

* "Observe" mode becomes "Analytics" mode,
* "Infrastructure" mode becomes "Subscription Management" mode.

After the initialization, you can access the Qonversion instance whenever you want as follows:

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance();
  ```
</CodeGroup>

So you should replace all your Qonversion calls with the construction above.

Also, if you were using `Qonversion.SetDebugMode()` for testing purposes, you should now call the `SetEnvironment(Environment.Sandbox)` method of the `QonversionConfigBuilder`.

## Entitlements

We are on the way to renaming permissions to entitlements as this naming suits more what it is used for. So, the following objects and methods were renamed in this release:

| Version \<4                | Version 4+                    |
| -------------------------- | ----------------------------- |
| Permission                 | Entitlement                   |
| QProductRenewState         | QEntitlementRenewState        |
| QPermissionSource          | QEntitlementSource            |
| PermissionsCacheLifetime   | EntitlementsCacheLifetime     |
| CheckPermissions           | CheckEntitlements             |
| OnPermissionsReceived      | OnEntitlementsReceived        |
| OnUpdatedPurchasesReceived | OnUpdatedEntitlementsReceived |
| UpdatedPurchasesReceived   | UpdatedEntitlementsReceived   |

The `Entitlement` class contains the same information as the `Permission` with a renaming of the `PermissionID` field - now it's named simply `Id`.

There is no `SetPermissionsCacheLifetime` method in Qonversion. You should provide `EntitlementsCacheLifetime` to `QonversionConfigBuilder` during the initialization using the `SetEntitlementsCacheLifetime` method.

<CodeGroup>
  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      )
      .SetEntitlementsCacheLifetime(EntitlementsCacheLifetime.Year)
      .Build();
  Qonversion.Initialize(config);
  ```
</CodeGroup>

## Automation changes

We've also changed the way the `Automations` is used. As in Qonversion, you should use `Automations` via the shared instance. On the first access, it will be initialized and returned. Then the initialized instance will be used.

<Info>
  You should access the shared instance of `Automations` strictly after you initialize Qonversion, else an exception will be thrown.
</Info>

<CodeGroup>
  ```csharp Unity theme={null}
  QonversionConfig config = new QonversionConfigBuilder(
          "projectKey",
          LaunchMode.SubscriptionManagement
      ).Build();
  Qonversion.Initialize(config);
  Automations.GetSharedInstance().SetDelegate(...);
  ```
</CodeGroup>

Also, the methods for working with push notifications were moved from `Qonversion` to `Automations`, so if you were using the following methods:

* `SetNotificationsToken`,
* `HandleNotification`,
* `GetNotificationCustomPayload`, make sure to make calls from the Automations instance instead of the Qonversion one.

## Rest of the changes

Along with the changes described above, there are several technical improvements and other changes in the new major release:

* all the internal classes were moved to the `Internal` package, and DTO classes were moved to the `Dto` package to make the library file structure more readable;
* the deprecated methods `SetUserID` and `Purchase` methods with `OnPermissionsReceived` callbacks were removed. `SetUserID` should be replaced with the `setProperty` call with the `UserProperty.CustomUserId` parameter.
* added the new method `UserInfo`, which returns the information about the current Qonversion user. Now it contains internal Qonversion and identity identifiers. The user info may be extended in future releases;
* added new enum values - `QOfferingTag.Unknown` and `QTrialDuration.Unknown`, which are used when parsing fails;
* the `EntitlementsCacheLifetime` enum values were rewritten in UpperCamelCase to meet the rest enums style;
* added new values `AppleSearchAds` and `AppleAdServices` to the `AttributionProvider` enum,
* the following methods, classes, and values renamings took place:

| Old name                                  | New name                           |
| ----------------------------------------- | ---------------------------------- |
| `AddAttributionData`                      | `Attribution`                      |
| `CheckTrialIntroEligibilityForProductIds` | `CheckTrialIntroEligibility`       |
| `SetAdvertisingID`                        | `CollectAdvertisingId`             |
| `SetAppleSearchAdsAttributionEnabled`     | `CollectAppleSearchAdsAttribution` |
| `AttributionSource`                       | `AttributionProvider`              |

***

[React Native 4.+ migration guide](react-native-4-migration-guide)

[AI-Ready: Visit our llms.txt file](llmtxt)


# Unity 6.+ migration guide
Source: https://documentation.qonversion.io/docs/unity-6-migration-guide

Historical migration guide for upgrading the Qonversion Unity SDK to major version 6.+: renamed entities and methods with a before/after reference for updating your integration.

## Upgrading version

Increase the dependency version in your Packages/manifest.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json manifest.json theme={null}
  "com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#6.0.0"
  ```
</CodeGroup>

## Renamings

In this major version, we have renamed several entities and public methods to make our namings more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade    | After upgrade           |
| ----------------- | ----------------------- |
| `UserProperty`    | `UserPropertyKey`       |
| `setUserProperty` | `setCustomUserProperty` |
| `setProperty`     | `setUserProperty`       |

## User properties changes

As mentioned above, we have renamed the`UserProperty` enum to `UserPropertyKey`. It was made to release the name `UserProperty` for a class, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().UserProperties((userProperties, error) =>
  {
      if (error != null)
      {
          // Handle the error  
          Debug.LogError("Error" + error);   
      }
      else
      {
          userProperties.Properties.ForEach(userProperty => {
              Debug.Log("User property - key: " + userProperty.Key + ", value: " + userProperty.Value);
          });
      }
  });
  ```
</CodeGroup>

`UserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `Properties`               | List of all user properties                                                 |
| `DefinedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `CustomProperties`         | Subset of all user properties, which were set using custom keys             |
| `FlatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `FlatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `FlatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                 | Description                                                                                              |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `GetProperty`        | `key` - string            | Searches for a property with the given property `key` in all properties list                             |
| `GetDefinedProperty` | `key` - `UserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `UserPropertyKey` enum with a `Custom` key to represent all the custom properties.

***

[React Native 6.+ migration guide](react-native-6-migration-guide)

[Cordova 4.+ migration guide](cordova-4-migration-guide)


# Unity SDK 6.x to 7.x migration guide
Source: https://documentation.qonversion.io/docs/unity-7-migration-guide

We've upgraded the Google Play Billing Library dependency on Android to version 6 in this release, which has led to major changes in the product and subscription management parts of our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *Packages/manifest.json* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json manifest.json theme={null}
  "com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#7.0.0"
  ```
</CodeGroup>

## Product updates

### Qonversion and Google Play product link changes

Google Play has recently upgraded the structure of their subscription products. We've written about it [in our blog](https://qonversion.io/blog/google-play-billing-library-5-0/). In short, they combined the same subscriptions with different durations into a single subscription with different base plans. In addition, they announced different kinds of offers to base plans, including free trials or introductory prices. In this release, we begin to support those changes.

Previously Qonversion **subscription** products required a Google Play subscription identifier. Now you can also set a specific **base plan** for the subscription. Different base plans of the same subscription can be linked to different Qonversion products. Let's have a look at an example.

Let's say you sell monthly and annual subscriptions in your app, both on Android and iOS. With the previous Qonversion SDK versions, you would specify two Qonversion products (`premium_monthly` and `premium_annual`), two App Store products (`premium_monthly_ios` and `premium_annual_ios`), and two Google Play products (`premium_monthly_android` and `premium_annual_android`). Then you would link those store products to Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_monthly_android`,

`premium_annual` - `premium_annual_ios` and `premium_annual_android`.

With the new Google Play Subscriptions structure, you can create only one subscription for Android - `premium_android` and two base plans for it (`monthly` and `annual`). With this done, you can now use a single subscription for both Qonversion products as follows:

`premium_monthly` - `premium_monthly_ios` and `premium_android` with `monthly` base plan,

`premium_annual` - `premium_annual_ios` and `premium_android` with `annual` base plan.

### Store details for the `QProduct` class

Speaking of the SDK side - the first big part of the changes is the addition of the new `BasePlanId` field to `Product` which can be set to the product via Qonversion Dashboard.

We have deprecated the `Product.SkuDetails` field, because `SkuDetails` contain information only for backward compatible base plans and are now deprecated in the Google Play Billing Library. Instead, we have added the new `StoreDetails` field of type `ProductStoreDetails`, which contains all the store information for the Google Play Product. You can find the specifications of that class [on this page](google-play-product-details).

If `BasePlanId` is not specified for a product, it means one of the following:

* it is a one-time (in-app) product that can not have any base plans,
* it is a product that was not updated in the Qonversion dashboard after this version was released,
* it is an iOS-only product.

In the case of the in-app product, both `SkuDetails` and `StoreDetails` fields will contain information about that in-app. But in the second case, when there is a subscription product without a specified base plan, the `SkuDetails` field will contain information about the **backward compatible** base plan, while the `StoreDetails` field will only contain common subscription information without base-plan-specific data. It means that you should start using `StoreDetails` field for base-plan-specific data (like price, duration, and so on) for Android subscription products only if you've specified their base plan IDs in Qonversion product settings.

### The other `Product` fields changes

Along with the above changes, we have changed the `Type` field and removed the `Duration` and `TrialDuration` fields from the product class. The `Type` and `Duration` were previously being set via the dashboard, and the `TrialDuration` was calculated from the store details and was represented as an enumeration with several common durations. Now, the product `Type` is calculated from the store details both for Android and iOS. We've also added the `Intro` value to `ProductType` to separate `trial` and `intro` products (Android only for now). An `Unknown` value was also added for the cases where we are unable to determine the product type. The `Duration` and `TrialDuration` fields were replaced with `SubscriptionPeriod` and `TrialPeriod`. Both properties are of type `SubscriptionPeriod` and the values are also calculated from the store details for both platforms.

The last thing to note is that we've also changed the `PrettyPrice` and `PrettyIntroductoryPrice` fields calculation for Android. Earlier they were calculated from `SkuDetails`, while now we first try to use `StoreDetails` if possible and only then fall back to `SkuDetails`.

### `Product` updates summary

Below is the shortened summary of the `Product` changes:

* new `BasePlanId` field, specifying concrete subscription base plan for Google Play subscriptions, added,
* `SkuDetails` field deprecated,
* new `StoreDetails` field, containing information about Google Play product, added;
* the `Type` field is now calculated based on store details both for Android and iOS, instead of the value set via the Qonversion dashboard. The `Intro` and `Unknown` values were added to `ProductType` to separate cases of trial and intro products (Android only for now) and also the case when we are unable to determine the product type;
* the `Duration` and `TrialDuration` fields were replaced with `SubscriptionPeriod` and `TrialPeriod` fields of type `SubscriptionPeriod` with the values calculated from the store details both for Android and iOS;
* the `PrettyPrice` and `PrettyIntroductoryPrice` fields on Android now prefers `StoreDetails` to get the price from, and only then - `SkuDetails`.

## Purchase flow updates

In this release, we have changed the `Purchase` and `UpdatePurchase` methods signatures. Previously there were several methods for different sets of arguments. Now we've arranged all those properties into classes - `PurchaseModel` and `PurchaseUpdateModel`, that should be instantiated and provided to the single `Purchase` or `UpdatePurchase` method.

You can create instances of those classes either manually or by using the utility functions `ToPurchaseModel` and `ToPurchaseUpdateModel` added to the `Product` class.

Below is an example of how the `Purchase` flow has changed:

<CodeGroup>
  ```csharp Unity theme={null}
  // Old
  Qonversion.GetSharedInstance().PurchaseProduct(product, (entitlements, error, isCancelled) => {...});

  // New
  PurchaseModel purchaseModel = product.ToPurchaseModel();
  Qonversion.GetSharedInstance().Purchase(purchaseModel, (entitlements, error, isCancelled) => {...});
  ```
</CodeGroup>

And an `UpdatePurchase` flow example:

<CodeGroup>
  ```csharp Unity theme={null}
  // Old
  Qonversion.GetSharedInstance().UpdatePurchaseWithProduct(newProduct, "oldProductId", (entitlements, error, isCancelled) => {...});

  // New
  PurchaseUpdateModel purchaseUpdateModel = product.ToPurchaseUpdateModel("oldProductId");
  Qonversion.GetSharedInstance().UpdatePurchase(purchaseUpdateModel, (entitlements, error, isCancelled) => {...});
  ```
</CodeGroup>

If you were using only product identifiers, you can create purchase models manually as follows:

<CodeGroup>
  ```csharp Unity theme={null}
  // Old
  Qonversion.GetSharedInstance().PurchaseProduct("productId", (entitlements, error, isCancelled) => {...});

  // New
  PurchaseModel purchaseModel = new PurchaseModel("newProductId");
  Qonversion.GetSharedInstance().Purchase(purchaseModel, (entitlements, error, isCancelled) => {...});
  ```
</CodeGroup>

<CodeGroup>
  ```csharp Unity theme={null}
  // Old
  Qonversion.GetSharedInstance().UpdatePurchase("newProductId", "oldProductId", (entitlements, error, isCancelled) => {...});

  // New
  PurchaseUpdateModel purchaseUpdateModel = new PurchaseUpdateModel("newProductId", "oldProductId");
  Qonversion.GetSharedInstance().UpdatePurchase(purchaseUpdateModel, (entitlements, error, isCancelled) => {...});
  ```
</CodeGroup>

If necessary, you can provide a specific offer for subscription purchase.

<CodeGroup>
  ```csharp Unity theme={null}
  // Specifying offer via the `ToPurchaseModel` method:
  ProductOfferDetails productOfferDetails = ...; // Choose an offer from `StoreDetails`
  PurchaseModel purchaseModel = product.ToPurchaseModel(productOfferDetails);

  // Specifying offer ID via the `ToPurchaseModel` method:
  PurchaseModel purchaseModel = product.ToPurchaseModel("offer_id");

  // Specifying offer ID via the constructor:
  PurchaseModel purchaseModel = PurchaseModel("productId", "offer_id");
  PurchaseUpdateModel purchaseUpdateModel = PurchaseUpdateModel("newProductId", "oldProductId", "offer_id");

  // Specifying offer ID after the purchase model creation:
  purchaseModel.OfferId = "offer_id";
  ```
</CodeGroup>

If provided, we will try to find and purchase the offer with the specified ID for the requested Qonversion product. If there is no offer with the specified ID, an error will be returned. If no offer ID is provided for the subscription purchase of Qonversion product with a specified base plan ID, then we will choose the most profitable offer for the client from all the available offers. We calculate the cheapest price for the client by comparing all the trial or intro phases and the base plan. For iOS, old Qonversion products (where the base plan ID is not specified), or in-app products, the offer ID is ignored.

You can also remove any intro/trial offer from the purchase (use only a bare base plan). For that purpose, you should call `RemoveOffer` method of purchase model:

<CodeGroup>
  ```csharp Unity theme={null}
  purchaseModel.RemoveOffer();
  ```
</CodeGroup>

## The other changes

* The `CheckTrialIntroEligibility` method improved and now detects the eligibility based on store details on Android;
* The `ProductDuration` and `TrialDuration` classes were removed;
* The `ProrationMode` enum was removed and replaced with `PurchaseUpdatePolicy` ([read more](making-purchases)).

***

[React Native SDK 6.x to 7.x migration guide](react-native-7-migration-guide)

[Cordova SDK 4.x to 5.x migration guide](cordova-5-migration-guide)


# Unity SDK 7.x to 8.x migration guide
Source: https://documentation.qonversion.io/docs/unity-8-migration-guide

We've upgraded the Google Play Billing Library dependency for Android to version 7 in this release, leading to several changes in our SDK. These are described below.

## Upgrading version

Increase the dependency version in your *Packages/manifest.json* file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json manifest.json theme={null}
  "com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#8.0.0"
  ```
</CodeGroup>

## Android deployment upgrades

With the new Google Play Billing Library 7 we've increased our `minSdkVersion` to 21 and `targetSdkVersion` to 34 for Android.

If you were using lower `minSdkVersion` you should upgrade it to 21 to use the latest version of our SDK and Google Play Billing Library. If you have already targeted the 21+ version, you should do nothing.

## Installment plans support

In the latest library version, Google introduces installment plans, when a customer commits to pay for several subsequent subscription periods. In our release, we've added a new field `InstallmentPlanDetails` to `ProductOfferDetails` with the details of the installment plan if they exist. It contains the following information:

| Field                               | Type | Description                                                               |
| ----------------------------------- | ---- | ------------------------------------------------------------------------- |
| `CommitmentPaymentsCount`           | Int  | Committed payments count after a user signs up for this subscription plan |
| `SubsequentCommitmentPaymentsCount` | Int  | Subsequent committed payments count after this subscription plan renews   |

We've also added an `IsInstallment` flag to `ProductStoreDetails` to check if the current product has an installment plan or not.

Below is an example of those fields usage:

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Products((products, error) => {
    var installmentProduct = products["android_installment"];
    var storeDetails = installmentProduct?.StoreDetails;
    if (storeDetails?.IsInstallment == true) {
      var installmentPlanDetails = storeDetails.BasePlanSubscriptionOfferDetails?.InstallmentPlanDetails;
      // Use the installment plan information
    }
  });
  ```
</CodeGroup>

## Fallback files

We're happy to introduce the fallback files support in this release to make our system reliability even higher. Fallback files allow your app to work as expected in rare cases of network connection or Qonversion API issues for new users without a cache available. This allows purchases and entitlements to be processed for new users even if the Qonversion API faces issues. This also makes it possible to receive remote configs for cases when the network connection is unavailable.

Fallback files are available both on iOS and Android.

Read more about the fallback files in [the documentation](system-reliability#fallback-files).

## Error codes

In this release, we have added the `QonversionErrorCode` enum with the list of defined Qonversion error codes. Now you can compare any error code with the defined one to check any specific case as follows:

<CodeGroup>
  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Purchase(
    ...,
    (entitlements, qonversionError, cancelled) => {
      if (qonversionError.Code == QErrorCode.StoreProductNotAvailable) {
        // The requested product is unavailable for purchase. 
      }
    });
  ```
</CodeGroup>

We've also changed the type of `QonversionError.Code` field from `string` to `QErrorCode`.

## The other changes

* Pending purchases support was added for prepaid subscriptions on Android.
* `EligibilityStatus` `NonIntroProduct` was renamed to `NonIntroOrTrialProduct` to better reflect the meaning.

***

[React Native SDK 7.x to 8.x migration guide](react-native-8-migration-guide)

[Cordova SDK 5.x to 6.x migration guide](cordova-6-migration-guide)


# Unity
Source: https://documentation.qonversion.io/docs/unity-sdk

Install Unity SDK to validate user receipts, get in-app subscription analytics, and 3-rd party integrations.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/unity-sdk?label=Latest%20Release)](https://github.com/qonversion/unity-sdk/releases)

## Install via Git URL

Available starting from Unity 2018.3. Just add this line to the *Packages/manifest.json* file of your Unity Project:

<CodeGroup>
  ```json manifest.json theme={null}
  "dependencies": {
      "com.qonversion.unity": "https://github.com/qonversion/unity-sdk.git#9.5.0"
  }
  ```
</CodeGroup>

## Install via OpenUPM

Qonversion SDK package is available on the [openupm registry](https://openupm.com/). You can install it via [openupm-cli](https://github.com/openupm/openupm-cli).

<CodeGroup>
  ```bash Terminal theme={null}
  openupm add com.qonversion.unity
  ```
</CodeGroup>

## Install Native Dependencies

Make sure your project contains the External Dependencies Manager package. Otherwise, iOS & Android dependencies won't be resolved. This can result in a package import issues. Here are the steps describing how to install the External Dependency Manager:

1. Download the last version of the [External Dependencies Manager](https://github.com/googlesamples/unity-jar-resolver/tags) package.
2. In the Unity Editor click **Import package** -> **Custom package**
3. Choose a file with the `.unitypackage` dependency from the folder you've downloaded before and install it.

After the installation, do the following:

1. For iOS - **Assets** -> **External Dependency Manager** -> **iOS Resolver** -> **Install Cocoapods**
2. For Android - **Assets** -> **External Dependency Manager** -> **Android Resolver** -> **Resolve**

Now you are ready to build and run your project!

## Kids Mode for Qonversion Unity SDK

In case you are building an App for Kids, please [follow this guide](kids-mode-sdk) to learn more about Kids Mode for Qonversion SDKs.

***

## Next steps

The SDK is installed. Choose the mode to implement — this determines how much code you write next.

<NextStepsChooseMode />


# Upgrade and Downgrade a Subscription
Source: https://documentation.qonversion.io/docs/upgrade-and-downgrade-a-subscription

Let users upgrade, downgrade, or crossgrade between subscriptions on iOS and Android using ranking levels and proration update policies.

## App Store

Kindly note that you do not need to change your code to support upgrades, downgrades, and crossgrades for iOS subscriptions in your app. All users can upgrade, downgrade, or crossgrade between subscriptions unlimited times.

According to [Apple Documentation](https://developer.apple.com/app-store/subscriptions/#ranking), if you offer multiple subscriptions with different prices tiers, you can assign each to a level in App Store Connect. Ranking your subscriptions determines the upgrade, downgrade, and crossgrade paths available:

**Upgrade.** User purchases a subscription that offers a higher level of service than their current subscription. They are immediately upgraded and receive a refund of the prorated amount of their original subscription. If you’d like users to instantly access more content or features, rank the subscription higher to make it an upgrade.

**Downgrade.** User selects a subscription that offers a lower level of service than their current subscription. The subscription continues until the next renewal date, then is renewed at the lower level and price.

**Crossgrade.** User switches to a new subscription of the equivalent level. If the subscriptions are the same duration, the new subscription begins immediately. If the durations are different, the new subscription goes into effect at the next renewal date.

In the following [blog post](<https://qonversion.io/blog/ios-subscription-upgrades-downgrades-and-service-levels/ >), you can find more information about setting up subscription groups in the App Store Connect.

## Google Play

In order to upgrade, downgrade, or change a subscription on the Google Play Store, call the standard [`purchase()` function with `setOldProduct` purchase options](making-purchases#3-update-purchases-android-only). You can also set the update policy to control how the change affects your subscribers. See [Upgrade and Downgrade in Google](google-upgrade-downgrade-or-change-subscription) for the full list of supported policies.

<Info>
  ### Qonversion supports five update policies: `ChargeFullPrice`, `ChargeProratedPrice`, `WithTimeProration`, `Deferred`, and `WithoutProration`. The default is `WithTimeProration`. See [Upgrade and Downgrade in Google](google-upgrade-downgrade-or-change-subscription) for what each one does.
</Info>

***

[Store Product Price Changes](store-product-price-changes)

[App Store Connect Shared Secret](ios-app-store-info-fields#2-generate-the-app-specific-shared-secret)


# User Identifiers
Source: https://documentation.qonversion.io/docs/user-identifiers

Share your User ID with Qonversion to manage user access on various devices and platforms.

User identification is essential for a mobile application with an in-app subscription. Each subscriber should have a User ID that identifies them within your app. With Qonversion, you can use different ways to identify your users within the app based on your requirements.

## 1. Qonversion User ID

Qonversion creates a unique User ID each time an app is installed and opened for the first time. To use **Qonversion User ID**, call the *userInfo* method. You can use Qonversion User ID for third-party integrations or other purposes like matching data from webhook notifications to your server.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().userInfo { user, error in
    // use user?.qonversionId
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] userInfo:^(QONUser * _Nullable user, NSError * _Nullable error) {
    // use [user qonversionId] if no error occurred
  }]
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().userInfo(new QonversionUserCallback() {
      @Override
      public void onSuccess(@NonNull QUser user) {
          // use user.getQonversionId()
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.userInfo(object : QonversionUserCallback {
      override fun onSuccess(user: QUser) {
          // use user.qonversionId
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final userInfo = await Qonversion.getSharedInstance().userInfo();
    // use userInfo.qonversionId
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript React Native theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().userInfo();
    // use userInfo.qonversionId
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().UserInfo((userInfo, error) =>
  {
      if (error == null)
      {
          // use userInfo.QonversionId
      }
      else
      {
          // Handle the error
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().userInfo();
    // use userInfo.qonversionId
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().userInfo();
    // use userInfo.qonversionId
  } catch (e) {
    // handle error here
  }
  ```

  ```bash curl theme={null}
  curl --location --request GET 'https://api.qonversion.io/v3/users/QON_38a2d811afd54a433587620f8696266e' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

  {"created":1658489733000,"environment":"prod","id":"QON_38a2d811afd54a433587620f8696266e","identity_id":"your_custom_user_id"}
  ```
</CodeGroup>

## 2. User ID for third-party Integrations

Qonversion SDK provides an asynchronous method to set your user ID, which will later be sent to third-party integrations you enabled.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.userID, value: "yourSideUserId")
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyUserID value:@"yourSideUserId"];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.CustomUserId, "yourSideUserId");
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.CustomUserId, "yourSideUserId")
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.customUserId, 'yourSideUserId');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.CustomUserId, "yourSideUserId");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');
  ```
</CodeGroup>

<Warning>
  Use User ID for third-party Integrations to attribute events to existing users in other platforms. For managing user access across multiple devices or Apple and Google app stores, use [User Identifiers](offline-sdk-mode).
</Warning>

## 3. User Identity

**User Identity allows cross-device & cross-platform user identification and access management.**

<Warning>
  Use the documentation below and the User Identity concept only if you want to manage user access across multiple devices or Apple, Google and Web platforms for users logged into their accounts within your apps.

  If you need to assign your user ID for analytical purposes, use the `setUserProperty()` method described above.
</Warning>

User identification is critical in building cross-platform apps where you want to manage user access based on payments across different platforms. This can be a complex task as users can log in and out of your application, use multiple devices, or reinstall the app. To provide flexible subscription infrastructure and consistent data, we have built a comprehensive solution using a combination of Qonversion IDs, your backend IDs, and the merging concept for users.

Qonversion lets you identify your signed-in users and unlock premium access across multiple devices. Use the `identify()` method to link a user to your signed-in subscriber. Call this method every time you want to use User Identity. For example, when a user logs in. User Identity provides a convenient way of managing premium access of your existing subscribers, including the following cases:

* A user reinstalls your app for any reason. Using the same User ID allows you to provide premium access linked to previously purchased products.
* A user logs in on several devices. You can provide premium access based on a subscription purchased on one of his devices.
* A user logs in on iOS and Android versions of your app. You can provide premium access based on a subscription purchased on one of the platforms.

### Logging in

When a user logs into his account, call `identify()`.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.shared().identify("your_custom_user_id") { user, error in
    // use user if necessary
  }
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] identify:@"your_custom_user_id"];

  // or the following option, if you want to get notified about the result.

  [[Qonversion sharedInstance] identify:@"your_custom_user_id" completion:^(QONUser * _Nullable user, NSError * _Nullable error) {
    // use user if necessary
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().identify("your_custom_user_id");

  // or the following option, if you want to get notified about the result.

  Qonversion.getSharedInstance().identify("your_custom_user_id", new QonversionUserCallback() {
      @Override
      public void onSuccess(@NonNull QUser user) {
          // use user if necessary
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.shared.identify("your_custom_user_id", object : QonversionUserCallback {
      override fun onSuccess(user: QUser) {
          // use user if necessary
      }

      override fun onError(error: QonversionError) {
          // handle error here
      }
  })
  ```

  ```dart Flutter theme={null}
  try {
    final userInfo = await Qonversion.getSharedInstance().identify("your_custom_user_id");
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript React Native theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Identify("your_custom_user_id")

  // or the following option, if you want to get notified about the result.

  Qonversion.GetSharedInstance().Identify("your_custom_user_id", (userInfo, error) =>
  {
      if (error == null)
      {
          // use userInfo if necessary
      }
      else
      {
          // Handle the error
          Debug.Log("Error" + error.ToString());
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const userInfo = await Qonversion.getSharedInstance().identify('your_custom_user_id');
    // use userInfo if necessary
  } catch (e) {
    // handle error here
  }
  ```

  ```bash curl theme={null}
  curl --location --request POST 'https://api.qonversion.io/v3/identities/new_identities_user' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "user_id": "QON_38a2d811afd54a433587620f8696266e"
  }'

  {
      "id": "new_identities_user",
      "user_id": "QON_38a2d811afd54a433587620f8696266e"
  }
  ```
</CodeGroup>

<Warning>
  Always use unique user ID values. Otherwise, a user can get matched to another user's premium status.
</Warning>

To check entitlements for identified users, you can call [checkEntitlements()](check-permissions). You can check the details of setting up entitlements [here](entitlements).

### Logging out

You need to call the `logout()` method to handle entitlements for an unauthorized user. Call this method when a user logs out within your app:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().logout()
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] logout];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.logout()
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().Logout();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().logout();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().logout();
  ```
</CodeGroup>

When a user logs back into his account, **don't forget to use`identify()` method again.**

### Examples

Let's look at the following examples to understand better `Qonversion.identify()`.

<Warning>
  ### In the following examples:

  * Anonymous ID corresponds to the same app store account (Apple or Google).
  * A and B correspond to two different app store accounts (Apple or Google).
</Warning>

### Example 1. No User Identity.

Two anonymous users install the app using separate devices and subscribe without using the`identify()` method. These users have not been linked to each other.

| Anonymous ID | User ID | Action                                     |
| ------------ | ------- | ------------------------------------------ |
| A            | null    | Install                                    |
| B            | null    | Install                                    |
| B            | null    | Start Subscription X -> Gets Entitlement X |
| A            | null    | Start Subscription Y -> Gets Entitlement Y |

Now let's look at the `identify()` way of usage.

### Example 2. Single User Identity for two separate devices.

Let's consider the following user flow:

1. A user installs the app on his iPhone (first device).
2. He installs the same app on his second device (iPad/Android device/etc).
3. He makes a purchase and creates an account on the second device.
4. He uses the same credentials to log into the app on his iPhone (first device).

| Anonymous ID | User ID     | Action                                        |
| ------------ | ----------- | --------------------------------------------- |
| A            | null        | Install                                       |
| B            | null        | Install                                       |
| B            | null        | Start Subscription X -> Gets Entitlement X    |
| B            | user\_id\_1 | identify("user\_id\_1")                       |
| A            | user\_id\_1 | identify("user\_id\_1") -> Gets Entitlement X |

In this case, Qonversion will provide users `A` and `B` the same entitlements while they use the same `user_id_1`.

### Example 3. One anonymous user logs in & logs out.

Let's consider the following user flow:

1. A user installs the app and subscribes to the product `X`.
2. He creates his user account in the app with the following ID: `user_id_1`.
3. Then he purchases the product `Y` using the same app store account.
4. The user logs out from the app.

In this case, the user keeps having entitlements based on both products, `X` and `Y` since the purchases were made using the same app store account.

| Anonymous ID | User ID                                     | Action                                          |
| ------------ | ------------------------------------------- | ----------------------------------------------- |
| A            | null                                        | Install                                         |
| A            | null                                        | Start Subscription X -> Gets Entitlement X      |
| A            | user\_id\_1 (login for the very first time) | identify("user\_id\_1")                         |
| A            | user\_id\_1                                 | Purchase product Y -> Gets Entitlement Y        |
| A            | null                                        | Logout                                          |
| A            | null                                        | Entitlement X & Entitlement Y are still granted |

### Example 4. Two different anonymous users log in & Log out.

Let's consider the following user flow:

1. User `A` installs the app and subscribes for the product `X`.
2. User `A` logs into `user_id_1` account.
3. User `A` purchases product `Y`. Now User `A` has both entitlements `X` and `Y` granted.
4. User `B` installs the app and logs in with `user_id_1` credentials. Based on the User's Identity details, he also can use the app considering entitlements `X` and `Y` are granted.
5. User `A` logs out using the `logout()` method, he still has entitlements granted based on both purchases he has made on the device.
6. User `B` logs out and loses all the entitlements. His anonymous account has no purchases associated with him, as no purchases were made on his device.
   1. It is worth mentioning, in this case, User `A` and User `B` have different store accounts on their devices.

| Anonymous ID | User ID                                     | Action                                             |
| ------------ | ------------------------------------------- | -------------------------------------------------- |
| A            | null                                        | Install                                            |
| A            | null                                        | Start Subscription X -> Gets Entitlement X         |
| A            | user\_id\_1 (login for the very first time) | identify("user\_id\_1")                            |
| A            | user\_id\_1                                 | Purchase product Y -> Gets Entitlement Y           |
| B            | null                                        | Install                                            |
| B            | user\_id\_1                                 | identify("user\_id\_1") -> Gets Entitlements X & Y |
| A            | null                                        | Log out -> Keeps having Entitlements X & Y         |
| B            | null                                        | Log out -> Loses Entitlements X & Y                |

### Example 5. Two accounts with two separate purchases.

Let's consider the following user flow:

1. User `A` and User `B` install the app using separate devices.
   1. User `A` and User `B` have different store accounts on their devices.
2. User `A` subscribes to product `X`
3. User `B` subscribes to product `Y`.
4. User `A` then logs in with the ID `user_id_1` for the very first time. At this moment, this user ID is created and Entitlement `X` attaches to the `user_id_1` User Identity.
5. User `B` logs in with the same ID `user_id_1`.
6. User `B` now has Entitlement `X` (based on the User Identity) on top of Entitlement `Y`.
7. User `A` logs out, he still has Entitlement `X` (based on the device purchases).
8. User `B` logs out, he loses Entitlement `X` but still has Entitlement `Y` (based on the device purchases).

| Anonymous ID | User ID                                     | Action                                                                |
| ------------ | ------------------------------------------- | --------------------------------------------------------------------- |
| A            | null                                        | Install                                                               |
| B            | null                                        | Install                                                               |
| A            | null                                        | Start Subscription X -> Gets Entitlement X                            |
| A            | user\_id\_1 (login for the very first time) | identify("user\_id\_1")                                               |
| B            | null                                        | Start Subscription Y -> Gets Entitlement Y                            |
| B            | user\_id\_1                                 | identify("user\_id\_1") -> Gets Entitlement X and Keeps Entitlement Y |
| A            | null                                        | Log out -> Keeps having Entitlement X                                 |
| B            | null                                        | Log out -> Loses Entitlement X but still has Entitlement Y            |

### Example 6. Two accounts log in using the same device with one active purchase.

<Info>
  ### Activate this behaviour in entitlements

  For enabling this feature, navigate to the [entitlements settings section](https://dash.qonversion.io/entitlements/transferring) and modify the coping strategy setting to "Transfer entitlement." [Read more here](transferring)
</Info>

Let's consider the following user flow:

1. User `A` installs the app on his iOS device and subscribes for the product `X`.
2. User `A` logs into `user_id_1` account. Now Identity user `user_id_1` has Entitlement `X`
3. User `A'` installs the app on his Android device and logs into `user_id_1` account. Now User `A'` can get access to the Entitlement `X` - based content on his Android device.
4. User `B` takes User `A`'s iOS device and logs him out from the app.
5. User `B` logs into `user_id_2` account and restores subscription. Now Identity user `user_id_1` stops having Entitlement `X`, as it has been transferred to Identity user `user_id_2`
6. User `A` being logged in his Android device with `user_id_1` account stops having access to the Entitlement `X` - based content. Now only Identity user `user_id_2` is entitled to it.

| Anonymous ID | User ID     | Action                                                                          |
| ------------ | ----------- | ------------------------------------------------------------------------------- |
| A            | null        | iOS device install                                                              |
| A            | null        | Start Subscription X -> Gets Entitlement X                                      |
| A            | user\_id\_1 | identify("user\_id\_1")                                                         |
| A'           | null        | Android device install                                                          |
| A'           | user\_id\_1 | identify("user\_id\_1") -> Gets Entitlement X for Android device                |
| B            | null        | iOS device log out                                                              |
| B            | user\_id\_2 | identify("user\_id\_2")                                                         |
| B            | user\_id\_2 | Subscription Restore -> Transfers Entitlement X to user\_id\_2 from user\_id\_1 |
| A'           | user\_id\_1 | Loses Entitlement X                                                             |

***

[Offline SDK mode](offline-sdk-mode)

[Restore behavior](transferring)


# User Properties
Source: https://documentation.qonversion.io/docs/user-properties

Set and retrieve custom and predefined user attributes for segmentation, analytics, and third-party platform integrations.

User properties are attributes you can set on a user level. You can send user properties to third-party platforms and use them in Qonversion for customer segmentation and analytics. Here is an example of user properties:

<Frame>
  <img />
</Frame>

## Usage

There are two types of user properties: Qonversion-defined and custom user properties.

## Defined User Properties

We defined some common case properties and provided API for adding them:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.email, value: "me@qonversion.io")
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyEmail value:@"me@qonversion.io"];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.Email, "me@qonversion.io");
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.Email, "me@qonversion.io")
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.email, 'me@qonversion.io');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.EMAIL, 'me@qonversion.io');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.Email, "me@qonversion.io");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.EMAIL, 'me@qonversion.io');
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.EMAIL, 'me@qonversion.io');
  ```
</CodeGroup>

The full list of the defined properties is provided below:

| Name                            | Key                              | Description                                                                                                                                        |
| ------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Email`                         | `\_q_email`                      | User Email. It can be used for cross-platform authorization and integrations with Qonversion.                                                      |
| `Name`                          | `\_q_name`                       | User Name                                                                                                                                          |
| `KochavaDeviceId`               | `\_q_kochava_device_id`          | Kochava Unique Device ID                                                                                                                           |
| `AppsFlyerUserId`               | `\_q_appsflyer_user_id`          | Customer user ID. It can be used to cross-reference your in-house data with AppsFlyer attribution data.                                            |
| `AdjustAdId`                    | `\_q_adjust_adid`                | Adjust Advertising ID                                                                                                                              |
| `CustomUserId`                  | `\_q_custom_user_id`             | Your Internal User ID. Use User ID for third-party [Integrations ](integrations-overview)to attribute events to existing users in other platforms. |
| `FacebookAttribution`           | `\_q_fb_attribution`             | Mobile Cookie from the user's device                                                                                                               |
| `FirebaseAppInstanceId`         | `\_q_firebase_instance_id`       | The identifier for a Firebase app                                                                                                                  |
| `AppSetId`                      | `\_q_app_set_id`                 | Unique user identifier for all the developer's applications on Android                                                                             |
| `AdvertisingId`                 | `\_q_advertising_id`             | Unique user identifier assigned to a mobile device on iOS                                                                                          |
| `PushWooshUserId`               | `\_q_pushwoosh_user_id`          | Unique user identifier assigned to Pushwoosh. Used for Pushwoosh integration.                                                                      |
| `PushWooshHwId`                 | `\_q_pushwoosh_hwid`             | Hardware identifier generated by Pushwoosh. Used for Pushwoosh integration.                                                                        |
| `AppMetricaDeviceId`            | `\_q_appmetrica_device_id`       | Device identifier from AppMetrica. Used for AppMetrica integration.                                                                                |
| `AppMetricaUserProfileId`       | `\_q_appmetrica_user_profile_id` | User profile identifier from AppMetrica. Used for AppMetrica integration.                                                                          |
| `TenjinAnalyticsInstallationId` | `\_q_tenjin_aiid`                | Installation identifier from Tenjin. Used for Tenjin integration.                                                                                  |

## Custom User Properties

Additionally, you can add custom user property. Qonversion can send them to third-party integrations as well. For example, you can add user details and use that data to send personalized emails or push notifications via Mailchimp and OneSignal integrations.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setCustomUserProperty("liked-app", value: "yes")
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setCustomUserProperty: @"liked-app" value: @"yes"];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setCustomUserProperty("liked-app", "yes");
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setCustomUserProperty("liked-app", "yes")
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setCustomUserProperty('liked-app', 'yes');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setCustomUserProperty('liked-app', 'yes');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetCustomUserProperty("liked-app", "yes");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setCustomUserProperty('liked-app', 'yes');
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setCustomUserProperty('liked-app', 'yes');
  ```
</CodeGroup>

You can use letters **A-Za-z**, numbers, and the following symbols **\_.:-** as a property key.

<Info>
  ### Property setting order

  To successfully set either Defined or Custom User Properties, launch Qonversion SDK first. [Learn more.](install-sdk)
</Info>

## Get User Properties

You can get user properties set for a current user as follows:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().userProperties({ userProperties, error in
    if let error = error {
      // Handle error
      return
    }

    userProperties?.properties.forEach({ userProperty in
      print("User property: ", "key: ", userProperty.key, ", value: ", userProperty.value)
    })
  });
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] userProperties:^(QONUserProperties * _Nullable userProperties, NSError * _Nullable error) {
    if (error) {
      // Handle error
      return;
    }

    [userProperties.properties enumerateObjectsUsingBlock:^(QONUserProperty * _Nonnull userProperty, NSUInteger idx, BOOL * _Nonnull stop) {
      NSLog(@"User property: key: %@, value: %@", userProperty.key, userProperty.value);
    }];
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().userProperties(new QonversionUserPropertiesCallback() {
      @Override
      public void onSuccess(@NonNull QUserProperties userProperties) {
          for (QUserProperty property : userProperties.getProperties()) {
              Log.d("User property", "Key: " + property.getKey() +
                      ", value: " + property.getValue());
          }
      }

      @Override
      public void onError(@NonNull QonversionError error) {
          // handle error here
      }
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.userProperties(object : QonversionUserPropertiesCallback {
    override fun onSuccess(userProperties: QUserProperties) {
      userProperties.properties.forEach {
        Log.d("User property", "key: ${it.key}, value: ${it.value}")
      }
    }

    override fun onError(error: QonversionError) {
      // handle error here
    }
  })
  ```

  ```dart Flutter theme={null}
  try {
    QUserProperties userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach((userProperty) {
      print('User property - key: ' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript React Native theme={null}
  try {
    const userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach(userProperty => {
      console.log('User property - key:' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().UserProperties((userProperties, error) =>
  {
      if (error != null)
      {
          // Handle the error
          Debug.LogError("Error" + error);
      }
      else
      {
          userProperties.Properties.ForEach(userProperty => {
              Debug.Log("User property - key: " + userProperty.Key + ", value: " + userProperty.Value);
          });
      }
  });
  ```

  ```typescript Cordova theme={null}
  try {
    const userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach(userProperty => {
      console.log('User property - key:' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```

  ```typescript Capacitor theme={null}
  try {
    const userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach(userProperty => {
      console.log('User property - key:' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

The object returned by `userProperties` method contains several utility fields and methods:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().userProperties({ userProperties, error in
    ...
    // List of all user properties
    let allProperties = userProperties?.properties

    // Subset of all user properties, which were set using Qonversion-defined keys
    let definedProperties = userProperties?.definedProperties

    // Subset of all user properties, which were set using custom keys
    let customProperties = userProperties?.customProperties

    // A flattened version of all user properties as a key-value map
    let flatPropertiesMap = userProperties?.flatPropertiesMap

    // A flattened version of defined user properties as a key-value map
    let flatDefinedPropertiesMap = userProperties?.flatDefinedPropertiesMap

    // A flattened version of custom user properties as a key-value map
    let flatCustomPropertiesMap = userProperties?.flatCustomPropertiesMap

    // Searches for a property with the given property key in all properties list
    let customProperty = userProperties?.property(for: "customKey")

    // Searches for a property with the given Qonversion-defined property key in the defined properties list.
    let emailProperty = userProperties?.definedProperty(for: .email)
  });
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] userProperties:^(QONUserProperties * _Nullable userProperties, NSError * _Nullable error) {
    ...
    // List of all user properties
    NSMutableArray<QONUserProperty *> *allProperties = userProperties.properties;

    // Subset of all user properties, which were set using Qonversion-defined keys
    NSMutableArray<QONUserProperty *> *definedProperties = userProperties.definedProperties;

    // Subset of all user properties, which were set using custom keys
    NSMutableArray<QONUserProperty *> *customProperties = userProperties.customProperties;

    // A flattened version of all user properties as a key-value map
    NSMutableDictionary<NSString *, NSString *> *flatPropertiesMap = userProperties.flatPropertiesMap;

    // A flattened version of defined user properties as a key-value map
    NSMutableDictionary<NSNumber *, NSString *> *flatDefinedPropertiesMap = userProperties.flatDefinedPropertiesMap;

    // A flattened version of custom user properties as a key-value map
    NSMutableDictionary<NSString *, NSString *> *flatCustomPropertiesMap = userProperties.flatCustomPropertiesMap;

    // Searches for a property with the given property key in all properties list
    QONUserProperty *customProperty = [userProperties propertyForKey:@"customKey"];

    // Searches for a property with the given Qonversion-defined property key in the defined properties list.
    QONUserProperty *emailProperty = [userProperties definedPropertyForKey:QONUserPropertyKeyEmail];
  }];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().userProperties(new QonversionUserPropertiesCallback() {
      @Override
      public void onSuccess(@NonNull QUserProperties userProperties) {
  			  // List of all user properties
          List<QUserProperty> allProperties = userProperties.getProperties();

    		  // Subset of all user properties, which were set using Qonversion-defined keys
          List<QUserProperty> definedProperties = userProperties.getDefinedProperties();

    		  // Subset of all user properties, which were set using custom keys
          List<QUserProperty> customProperties = userProperties.getCustomProperties();

    		  // A flattened version of all user properties as a key-value map
          Map<String, String> flatPropertiesMap = userProperties.getFlatPropertiesMap();

    		  // A flattened version of defined user properties as a key-value map
          Map<QUserPropertyKey, String> flatDefinedPropertiesMap = userProperties.getFlatDefinedPropertiesMap();

    		  // A flattened version of custom user properties as a key-value map
          Map<String, String> flatCustomPropertiesMap = userProperties.getFlatCustomPropertiesMap();

    		  // Searches for a property with the given property key in all properties list
          QUserProperty customProperty = userProperties.getProperty("customKey");

    		  // Searches for a property with the given Qonversion-defined property key in the defined properties list.
          QUserProperty emailProperty = userProperties.getDefinedProperty(QUserPropertyKey.Email);
      }

      ...
  });
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.userProperties(object : QonversionUserPropertiesCallback {
    override fun onSuccess(userProperties: QUserProperties) {
    	// List of all user properties
      val allProperties = userProperties.properties

    	// Subset of all user properties, which were set using Qonversion-defined keys
      val definedProperties = userProperties.definedProperties

    	// Subset of all user properties, which were set using custom keys
      val customProperties = userProperties.customProperties

    	// A flattened version of all user properties as a key-value map
      val flatPropertiesMap = userProperties.flatPropertiesMap

    	// A flattened version of defined user properties as a key-value map
      val flatDefinedPropertiesMap = userProperties.flatDefinedPropertiesMap

    	// A flattened version of custom user properties as a key-value map
      val flatCustomPropertiesMap = userProperties.flatCustomPropertiesMap

    	// Searches for a property with the given property key in all properties list
      val customProperty = userProperties.getProperty("customKey")

    	// Searches for a property with the given Qonversion-defined property key in the defined properties list.
      val emailProperty = userProperties.getDefinedProperty(QUserPropertyKey.Email)
    }
    ...
  })
  ```

  ```dart Flutter theme={null}
  var userProperties = await Qonversion.getSharedInstance().userProperties();

  // List of all user properties
  var allProperties = userProperties.properties;

  // Subset of all user properties, which were set using Qonversion-defined keys
  var definedProperties = userProperties.definedProperties;

  // Subset of all user properties, which were set using custom keys
  var customProperties = userProperties.customProperties;

  // A flattened version of all user properties as a key-value map
  var flatPropertiesMap = userProperties.flatPropertiesMap;

  // A flattened version of defined user properties as a key-value map
  var flatDefinedPropertiesMap = userProperties.flatDefinedPropertiesMap;

  // A flattened version of custom user properties as a key-value map
  var flatCustomPropertiesMap = userProperties.flatCustomPropertiesMap;

  // Searches for a property with the given property key in all properties list
  var customProperty = userProperties.getProperty("customKey");

  // Searches for a property with the given Qonversion-defined property key in the defined properties list.
  var emailProperty = userProperties.getDefinedProperty(QUserPropertyKey.email);
  ```

  ```typescript React Native theme={null}
  const userProperties = await Qonversion.getSharedInstance().userProperties();

  // List of all user properties
  const allProperties = userProperties.properties;

  // Subset of all user properties, which were set using Qonversion-defined keys
  const definedProperties = userProperties.definedProperties;

  // Subset of all user properties, which were set using custom keys
  const customProperties = userProperties.customProperties;

  // A flattened version of all user properties as a key-value map
  const flatPropertiesMap = userProperties.flatPropertiesMap;

  // A flattened version of defined user properties as a key-value map
  const flatDefinedPropertiesMap = userProperties.flatDefinedPropertiesMap;

  // A flattened version of custom user properties as a key-value map
  const flatCustomPropertiesMap = userProperties.flatCustomPropertiesMap;

  // Searches for a property with the given property key in all properties list
  const customProperty = userProperties.getProperty('customKey');

  // Searches for a property with the given Qonversion-defined property key in the defined properties list.
  const emailProperty = userProperties.getDefinedProperty(UserPropertyKey.EMAIL);
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().UserProperties((userProperties, error) =>
  {
      ...
  		// List of all user properties
      List<UserProperty> allProperties = userProperties.Properties;

  		// Subset of all user properties, which were set using Qonversion-defined keys
      List<UserProperty> definedProperties = userProperties.DefinedProperties;

  		// Subset of all user properties, which were set using custom keys
      List<UserProperty> customProperties = userProperties.CustomProperties;

  		// A flattened version of all user properties as a key-value map
      Dictionary<string, string> flatPropertiesMap = userProperties.FlatPropertiesMap;

  		// A flattened version of defined user properties as a key-value map
      Dictionary<UserPropertyKey, string> flatDefinedPropertiesMap = userProperties.FlatDefinedPropertiesMap;

  		// A flattened version of custom user properties as a key-value map
      Dictionary<string, string> flatCustomPropertiesMap = userProperties.FlatCustomPropertiesMap;

  		// Searches for a property with the given property key in all properties list
      UserProperty customProperty = userProperties.GetProperty("customKey");

  		// Searches for a property with the given Qonversion-defined property key in the defined properties list.
      UserProperty emailProperty = userProperties.GetDefinedProperty(UserPropertyKey.Email);
  });
  ```

  ```typescript Cordova theme={null}
  const userProperties = await Qonversion.getSharedInstance().userProperties();

  // List of all user properties
  const allProperties = userProperties.properties;

  // Subset of all user properties, which were set using Qonversion-defined keys
  const definedProperties = userProperties.definedProperties;

  // Subset of all user properties, which were set using custom keys
  const customProperties = userProperties.customProperties;

  // A flattened version of all user properties as a key-value map
  const flatPropertiesMap = userProperties.flatPropertiesMap;

  // A flattened version of defined user properties as a key-value map
  const flatDefinedPropertiesMap = userProperties.flatDefinedPropertiesMap;

  // A flattened version of custom user properties as a key-value map
  const flatCustomPropertiesMap = userProperties.flatCustomPropertiesMap;

  // Searches for a property with the given property key in all properties list
  const customProperty = userProperties.getProperty('customKey');

  // Searches for a property with the given Qonversion-defined property key in the defined properties list.
  const emailProperty = userProperties.getDefinedProperty(Qonversion.UserPropertyKey.EMAIL);
  ```

  ```typescript Capacitor theme={null}
  const userProperties = await Qonversion.getSharedInstance().userProperties();

  // List of all user properties
  const allProperties = userProperties.properties;

  // Subset of all user properties, which were set using Qonversion-defined keys
  const definedProperties = userProperties.definedProperties;

  // Subset of all user properties, which were set using custom keys
  const customProperties = userProperties.customProperties;

  // A flattened version of all user properties as a key-value map
  const flatPropertiesMap = userProperties.flatPropertiesMap;

  // A flattened version of defined user properties as a key-value map
  const flatDefinedPropertiesMap = userProperties.flatDefinedPropertiesMap;

  // A flattened version of custom user properties as a key-value map
  const flatCustomPropertiesMap = userProperties.flatCustomPropertiesMap;

  // Searches for a property with the given property key in all properties list
  const customProperty = userProperties.getProperty('customKey');

  // Searches for a property with the given Qonversion-defined property key in the defined properties list.
  const emailProperty = userProperties.getDefinedProperty(UserPropertyKey.EMAIL);
  ```
</CodeGroup>

## (Optional) Set User ID

If you want to implement cross-platform (Android, IOS, and Web) user entitlement management, please, follow the [User Identity guide](user-identifiers#3-user-identity).

To match Qonversion revenue events to users in [third-party tools](integrations-overview), you need to set the identical user IDs in all of them:

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().setUserProperty(.userID, value: "yourSideUserId")
  ```

  ```objectivec Objective-C theme={null}
  [[Qonversion sharedInstance] setUserProperty:QONUserPropertyKeyUserID value:@"yourSideUserId"];
  ```

  ```java Java theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.CustomUserId, "yourSideUserId");
  ```

  ```kotlin Kotlin theme={null}
  Qonversion.shared.setUserProperty(QUserPropertyKey.CustomUserId, "yourSideUserId")
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.customUserId, 'yourSideUserId');
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.CustomUserId, "yourSideUserId");
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.CUSTOM_USER_ID, 'yourSideUserId');
  ```
</CodeGroup>

The user ID improves the quality of events matching to the platforms where event attribution is not exclusively based on IDFA or GAID.

## (Optional) Set IDFA (Identifier for Advertisers, iOS 14.5+ only)

On iOS 14.5+, after requesting the app tracking permission using ATT, you need to notify Qonversion if tracking is allowed and IDFA is available. This will help to have precise attribution in Adjust, AppsFlyer, Singular and other [Qonversion integrations](integrations-overview).

<CodeGroup>
  ```swift Swift theme={null}
  ATTrackingManager.requestTrackingAuthorization { status in
      switch status {
      case .authorized:
          Qonversion.shared().collectAdvertisingId()

      // handle other states below
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
      switch (status) {
          case ATTrackingManagerAuthorizationStatusAuthorized:
              [[Qonversion sharedInstance] collectAdvertisingId];
              break;

          // handle other states if needed

          default:
            break;
      }
  }];
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().collectAdvertisingId();
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().collectAdvertisingId();
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().CollectAdvertisingId();
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().collectAdvertisingId();
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().collectAdvertisingId();
  ```
</CodeGroup>

## (Optional) Set ASID (App set ID, Android 12+ only)

On Android 12+, you can provide an App set ID to have it used in [Qonversion integrations](integrations-overview).

Add `com.google.android.gms:play-services-appset` as the dependency to your project and write the following code.

<CodeGroup>
  ```java Java theme={null}
  final AppSetIdClient client = AppSet.getClient(context);
  final Task<AppSetIdInfo> task = client.getAppSetIdInfo();
  task.addOnSuccessListener(info -> {
      final String id = info.getId();
      Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.AppSetId, id);
  });
  ```

  ```kotlin Kotlin theme={null}
  val client = AppSet.getClient(requireContext())
  client.appSetIdInfo.addOnSuccessListener { info: AppSetIdInfo ->
      Qonversion.shared.setUserProperty(QUserPropertyKey.AppSetId, info.id)
  }
  ```

  ```dart Flutter theme={null}
  Qonversion.getSharedInstance().setUserProperty(QUserPropertyKey.appSetId, appSetId);
  ```

  ```typescript React Native theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.APP_SET_ID, appSetId);
  ```

  ```csharp Unity theme={null}
  Qonversion.GetSharedInstance().SetUserProperty(UserPropertyKey.AppSetId, appSetId);
  ```

  ```typescript Cordova theme={null}
  Qonversion.getSharedInstance().setUserProperty(Qonversion.UserPropertyKey.APP_SET_ID, appSetId);
  ```

  ```typescript Capacitor theme={null}
  Qonversion.getSharedInstance().setUserProperty(UserPropertyKey.APP_SET_ID, appSetId);
  ```
</CodeGroup>

***

[Web SDK](web-sdk)

[Server Notifications](server-notifications)


# New users
Source: https://documentation.qonversion.io/docs/users

View analytics on new user acquisition, trial conversion rates, and paid subscription conversion by install cohort.

## Available Charts

### New Users Overview

This chart shows the number of new users detected by Qonversion SDK for the first time. Suppose you have integrated Qonversion SDK into the existing app with some active user base. In that case, those users will be counted towards new users (Installs) the first time they open the updated version of your app with Qonversion SDK. In that case, you can expect to see a higher number of installs in the first days after you have integrated Qonversion SDK. If you integrate Qonversion SDK into your app from the first release, the data on new users who first opened the app will be accurate immediately.

<Frame>
  <img />
</Frame>

### New-User-to-Trial Conversion

Calculated as the number of trial start events divided by the number of installs. → Numerator: Trial started events attributed to users who installed an app during the selected period → Denominator: Installs for the selected period

<Frame>
  <img />
</Frame>

### New-User-to-Paid Conversion

This chart shows what percentage of all new users are converting to paying customers, including the conversion split by type of initial purchase:

* Trial converted (the user initially started a trial, and that trial successfully converted)
* Subscription Started (the user started a subscription without a trial period)
* In-App Purchase (the user made a one-time non-recurring in-app purchase) The conversion is calculated as the ratio: → Numerator: trials converted events + subscription (without trial) started events + non-recurring in-app purchase events attributed to the install date for the selected period → Denominator: Installs for the selected period

<Frame>
  <img />
</Frame>

***

[Revenue](revenue)

[Trials](trials)


# Users and Access
Source: https://documentation.qonversion.io/docs/users-and-access

Users and Access section to manage the team roles in your Qonversion project.

Qonversion understands the importance of efficient collaboration and seamless teamwork when managing your app and subscription-based business. That's why we're thrilled to introduce our **Users and Access** tab, designed to simplify granting access, managing roles, and assigning projects within the Qonversion platform.

<Info>
  ### Note

  It is only possible to invite an email that is not yet registered in Qonversion. If your team member has already created a Qonversion account, send an invite to another email or contact Qonversion support.
</Info>

## User Roles

Whether working with a small team or a large organization, this feature empowers you to streamline collaboration, enhance productivity, and ensure the right people access the correct information.

| Permissions            | Admin | Manager | Analyst | Developer | Viewer |
| ---------------------- | ----- | ------- | ------- | --------- | ------ |
| Analytics              | ✅     | ✅       | ✅       | ❌         | ✅      |
| Apple Search Ads       | ✅     | ✅       | ✅       | ❌         | ✅      |
| Experiments            | ✅     | ✅       | ✅       | ✅         | ✅      |
| Customizable dashboard | ✅     | ✅       | ✅       | ❌         | ✅      |
| Events                 | ✅     | ✅       | ✅       | ✅         | ✅      |
| Entitlements           | ✅     | ✅       | ❌       | ✅         | ❌      |
| Store settings         | ✅     | ✅       | ❌       | ✅         | ❌      |
| Integrations settings  | ✅     | ✅       | ✅       | ❌         | ❌      |
| Raw Data Export        | ✅     | ✅       | ✅       | ❌         | ❌      |
| Adding new users       | ✅     | ✅       | ❌       | ❌         | ❌      |
| Billing information    | ✅     | ❌       | ❌       | ❌         | ❌      |
| ASA settings           | ✅     | ❌       | ❌       | ❌         | ❌      |
| No Codes Screens       | ✅     | ✅       | ❌       | ❌         | ❌      |

***

[Migrating from Adapty to Qonversion](adapty-migration-guide)

[Sandbox Data](testing)


# Using No-Codes with custom purchases handling
Source: https://documentation.qonversion.io/docs/using-no-codes-with-custom-purchases-handling

By default, Qonversion No-Codes utilize the Qonversion SDK for managing purchases. This implies that you should operate Qonversion in subscription management mode. However, if you have your own purchasing infrastructure, you can manage purchases and restores from No-Code screens on your end. It’s as straightforward as supplying a single delegate to Qonversion No-Codes prior to showing the screen.

Integrating Qonversion No-Codes with your own purchasing infrastructure necessitates:

* creating a product within the Qonversion dashboard and associating it with a purchase action on your screen,
* implementing and providing a `PurchaseDelegate` to Qonversion No-Codes that is responsible for managing purchase and restore requests from No-Code screens.

<Warning>
  ### Unity warning

  On Android, when a No-Codes screen is displayed, Unity's game loop is paused because the No-Codes screen runs as a separate Activity on top of Unity's Activity. This means that this delegate will only work on iOS, and will not work on Android.
</Warning>

## Implementing `PurchaseDelegate`

To handle purchase and restore requests from No-Code screens on your end, you should implement `PurchaseDelegate`. It has two simple methods - `purchase`, accepting the requested product, and `restore`.

<CodeGroup>
  ```swift Swift theme={null}
  extension MyPurchaseHandler: NoCodesPurchaseDelegate {
    func purchase(product: Qonversion.Product) async throws {
      // Execute the purchase as you wish here
      // You can throw exceptions in case of errors
    }
    
    func restore() async throws {
      // Execute the restore as you wish here
      // You can throw exceptions in case of errors
    }
  }
  ```

  ```kotlin Kotlin theme={null}
  // You can use either coroutine interface as follows:
  class MyPurchasesHandler : PurchaseDelegate {
      override suspend fun purchase(product: QProduct) {
          // Execute the purchase as you wish here
          // You can throw exceptions in case of errors
      }

      override suspend fun restore() {
          // Execute the restore as you wish here
          // You can throw exceptions in case of errors
      }
  }

  // Or you can use callbacks interface:
  class MyPurchaseHandler : PurchaseDelegateWithCallbacks {
      override fun purchase(
          product: QProduct,
          onSuccess: PurchaseDelegateWithCallbacks.OnSuccess,
          onError: PurchaseDelegateWithCallbacks.OnError
      ) {
          // Execute the purchase as you wish here
          // And call onSuccess once everything is done to close the No-Code screen
          onSuccess()
          // Call onError with exception in case of error.
      }

      override fun restore(
          onSuccess: PurchaseDelegateWithCallbacks.OnSuccess,
          onError: PurchaseDelegateWithCallbacks.OnError
      ) {
          // Execute the restore as you wish here
          // And call onSuccess once everything is done to close the No-Code screen
          onSuccess()
          // Call onError with exception in case of error.
      }
  }
  ```

  ```java Java theme={null}
  class MyPurchasesHandler implements PurchaseDelegateWithCallbacks {
      @Override
      public void purchase(@NonNull QProduct product, @NonNull OnSuccess onSuccess, @NonNull OnError onError) {
          // Execute the purchase as you wish here
          // And call onSuccess once everything is done to close the No-Code screen
          onSuccess.invoke();
          // Call onError with exception in case of error.
      }

      @Override
      public void restore(@NonNull OnSuccess onSuccess, @NonNull OnError onError) {
          // Execute the restore as you wish here
          // And call onSuccess once everything is done to close the No-Code screen
          onSuccess.invoke()
          // Call onError with exception in case of error.
      }
  }
  ```

  ```typescript React Native theme={null}
  class MyPurchaseDelegate implements PurchaseDelegate {
    async purchase(product: Product): Promise<void> {
      // Execute the purchase as you wish here
      // You can throw exceptions in case of errors
    }

    async restore(): Promise<void> {
      // Execute the restore as you wish here
      // You can throw exceptions in case of errors
    }
  }
  ```

  ```dart Flutter theme={null}
  class MyPurchaseDelegate implements NoCodesPurchaseDelegate {
    @override
    Future<void> purchase(QProduct product) async {
      // Execute the purchase as you wish here
      // You can throw exceptions in case of errors
    }

    @override
    Future<void> restore() async {
      // Execute the restore as you wish here
      // You can throw exceptions in case of errors
    }
  }
  ```

  ```csharp Unity theme={null}
  public class MyPurchaseDelegate : NoCodesPurchaseDelegate
  {
      public void Purchase(Product product, System.Action onSuccess, System.Action<string> onError)
      {
          // Execute the purchase as you wish here
          // Call onSuccess() when purchase completes successfully
          // Call onError("error message") in case of errors
          
          try
          {
              // Your purchase logic here
              onSuccess();
          }
          catch (System.Exception e)
          {
              onError(e.Message);
          }
      }

      public void Restore(System.Action onSuccess, System.Action<string> onError)
      {
          // Execute the restore as you wish here
          // Call onSuccess() when restore completes successfully
          // Call onError("error message") in case of errors
          
          try
          {
              // Your restore logic here
              onSuccess();
          }
          catch (System.Exception e)
          {
              onError(e.Message);
          }
      }
  }
  ```

  ```typescript Cordova theme={null}
  class MyPurchaseDelegate implements Qonversion.PurchaseDelegate {
    async purchase(product: Qonversion.Product): Promise<void> {
      // Execute the purchase as you wish here
      // You can throw exceptions in case of errors
    }

    async restore(): Promise<void> {
      // Execute the restore as you wish here
      // You can throw exceptions in case of errors
    }
  }
  ```

  ```typescript Capacitor theme={null}
  class MyPurchaseDelegate implements PurchaseDelegate {
    async purchase(product: Product): Promise<void> {
      // Execute the purchase as you wish here
      // You can throw exceptions in case of errors
    }

    async restore(): Promise<void> {
      // Execute the restore as you wish here
      // You can throw exceptions in case of errors
    }
  }
  ```
</CodeGroup>

## Providing `PurchaseDelegate`

Once you've implemented the `PurchaseDelegate`, you need to provide it to Qonversion No-Codes. There are two equal ways to do it - during the initialization via configuration or after - via the No-Codes method.

<CodeGroup>
  ```swift Swift theme={null}
  // Providing during the initialization
  let purchaseDelegate = MyPurchaseHandler()
  let configuration = NoCodesConfiguration(projectKey: "projectKey", purchaseDelegate: purchaseDelegate)
  NoCodes.initialize(with: configuration)

  // Or after initialization
  let purchaseDelegate = MyPurchaseHandler()
  NoCodes.shared.set(purchaseDelegate: purchaseDelegate)
  ```

  ```kotlin Kotlin theme={null}
  // Providing during the initialization
  val purchaseDelegate = MyPurchaseHandler()
  val noCodesConfig = NoCodesConfig.Builder(this, "projectKey")
      .setPurchaseDelegate(purchaseDelegate)
      .build()
  NoCodes.initialize(noCodesConfig)

  // Or after initialization
  val purchaseDelegate = MyPurchaseHandler()
  NoCodes.shared.setPurchaseDelegate(purchaseDelegate)
  ```

  ```java Java theme={null}
  // Providing during the initialization
  final PurchaseDelegateWithCallbacks purchaseDelegate = new MyPurchaseHandler();
  final NoCodesConfig noCodesConfig = new NoCodesConfig.Builder(this, "projectKey")
      .setPurchaseDelegate(purchaseDelegate)
      .build();
  NoCodes.initialize(noCodesConfig);

  // Or after initialization
  final PurchaseDelegateWithCallbacks purchaseDelegate = new MyPurchaseHandler();
  NoCodes.getSharedInstance().setPurchaseDelegate(purchaseDelegate);
  ```

  ```typescript React Native theme={null}
  // Providing during the initialization
  const purchaseDelegate = MyPurchaseHandler()
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .setPurchaseDelegate(purchaseDelegate)
    .build();
  NoCodes.initialize(noCodesConfig);

  // Or after initialization
  const purchaseDelegate = MyPurchaseHandler()
  NoCodes.getSharedInstance().setPurchaseDelegate(purchaseDelegate);
  ```

  ```dart Flutter theme={null}
  // Providing during the initialization
  final purchaseDelegate = MyPurchaseDelegate();
  final noCodesConfig = NoCodesConfigBuilder('projectKey')
      .setPurchaseDelegate(purchaseDelegate)
      .build();
  NoCodes.initialize(noCodesConfig);

  // Or after initialization
  final purchaseDelegate = MyPurchaseDelegate();
  await NoCodes.getSharedInstance().setPurchaseDelegate(purchaseDelegate);
  ```

  ```csharp Unity theme={null}
  // Providing during the initialization
  var purchaseDelegate = new MyPurchaseDelegate();
  var noCodesConfig = new NoCodesConfigBuilder("projectKey")
      .SetPurchaseDelegate(purchaseDelegate)
      .Build();
  NoCodes.Initialize(noCodesConfig);

  // Or after initialization
  var purchaseDelegate = new MyPurchaseDelegate();
  NoCodes.GetSharedInstance().SetPurchaseDelegate(purchaseDelegate);
  ```

  ```typescript Cordova theme={null}
  // Providing during the initialization
  const purchaseDelegate = MyPurchaseHandler()
  const noCodesConfig = new Qonversion.NoCodesConfigBuilder('projectKey')
    .setPurchaseDelegate(purchaseDelegate)
    .build();
  Qonversion.NoCodes.initialize(noCodesConfig);

  // Or after initialization
  const purchaseDelegate = MyPurchaseHandler()
  Qonversion.NoCodes.getSharedInstance().setPurchaseDelegate(purchaseDelegate);
  ```

  ```typescript Capacitor theme={null}
  // Providing during the initialization
  const purchaseDelegate = MyPurchaseHandler()
  const noCodesConfig = new NoCodesConfigBuilder('projectKey')
    .setPurchaseDelegate(purchaseDelegate)
    .build();
  NoCodes.initialize(noCodesConfig);

  // Or after initialization
  const purchaseDelegate = MyPurchaseHandler()
  NoCodes.getSharedInstance().setPurchaseDelegate(purchaseDelegate);
  ```
</CodeGroup>

## Availability

The described feature is available in the following SDK versions

| Platform     | SDK version     |
| ------------ | --------------- |
| iOS          | 6.1.0+          |
| Android      | No-Codes 1.2.1+ |
| React Native | 10.1.0+         |
| Flutter      | 11.1.0+         |
| Unity        | 9.0.0+          |
| Cordova      | 7.0.0+          |
| Capacitor    | 1.0.0+          |

***

[Success and Failure Actions](success-failure-actions)

[Create Remote Config](remote-config)


# Variables
Source: https://documentation.qonversion.io/docs/variables-1

Variables let you display dynamic product data — such as price, currency, and trial period — directly inside your paywall or onboarding screen.

They automatically pull real-time values from your connected stores (App Store, Google Play) through Qonversion, so your content always stays accurate without manual edits.

<Frame>
  <img />
</Frame>

***

## What You Can Do with Variables

* **Display live pricing and offer details** inside Text, Heading, or Button components.
* **Localize values automatically** based on the user’s store region.
* **Avoid app updates** — when prices or durations change in the store, your screen updates instantly.

***

## Accessing Variables

You can add a variable in any **Text**, **Heading**, or **Button** by typing or `{{`in the text field — or by opening the **Variables** picker from the right panel.

**The picker shows:**

* A searchable list of all available variables.
* Example values for each variable, pulled from your connected products.
* Product selection dropdown (to link variables with a specific product).

<Info>
  Tip: Make sure your products are connected in Qonversion before using variables — the picker displays only sample data
</Info>

<Frame>
  <img />
</Frame>

***

## How Variables Work

Each variable is tied to a product identifier and a specific property (like price or duration). You can insert them using the `{{}}` syntax inside text or button labels:

```
{{products.product_id.price_per_month}} / month
```

When the screen loads, this will automatically show something like: **\$8.99 / month**

***

## Example Use Cases

| **Use Case**                | **Example Variable**                                                                  | **Rendered Output** |
| --------------------------- | ------------------------------------------------------------------------------------- | ------------------- |
| Show annual price per month | `{{products.annual.price_per_month}} / month`                                         | \$8.99 / month      |
| Show monthly price per year | `{{products.monthly.price_per_year}} / year`                                          | \$49.99 / year      |
| Show trial info             | `{{products.monthly.trial_period_unit_count}} {{products.monthly.trial_period_unit}}` | 7 days              |
| Show currency               | `{{products.monthly.currency_symbol}}`                                                | \$                  |
| Show full price             | `{{products.monthly.price}}`                                                          | \$14.99             |

***

## Variable Reference

| **Variable**              | **Example Value** | **Description**                           |
| ------------------------- | ----------------- | ----------------------------------------- |
| `store_name`              | `annual`          | Internal product name.                    |
| `price`                   | `$14.99`          | Formatted current product price.          |
| `price_raw`               | `14.99`           | Numeric price without currency.           |
| `price_per_day`           | `0.16`            | Price per day (calculated).               |
| `price_per_week`          | `1.15`            | Price per week (calculated).              |
| `price_per_month`         | `5.00`            | Price per month (calculated).             |
| `price_per_year`          | `59.96`           | Price per year (calculated).              |
| `currency_code`           | `USD`             | ISO currency code.                        |
| `currency_symbol`         | `$`               | Currency symbol.                          |
| `period_unit`             | `month`           | Product period (e.g., week, month, year). |
| `period_unit_count`       | `3`               | Number of units in the billing period.    |
| `period_iso`              | `P3M`             | ISO 8601 formatted period.                |
| `trial_period_unit`       | `week`            | Trial period unit.                        |
| `trial_period_unit_count` | `1`               | Trial duration count.                     |
| `intro_price`             | `10.99`           | Introductory offer price.                 |
| `intro_period_unit`       | `week`            | Unit for introductory period.             |
| `intro_period_unit_count` | `1`               | Count of introductory units.              |

***

## More Usage Examples

| Variable                                        | Weekly Example | Monthly Example | 2 Month Example | 3 Month Example | 6 Month Example | Annual Example | Lifetime Example |
| ----------------------------------------------- | -------------- | --------------- | --------------- | --------------- | --------------- | -------------- | ---------------- |
| products.product\_id.store\_name                | Premium        | Premium         | Premium         | Premium         | Premium         | Premium        | Premium          |
| products.product\_id.price                      | \$3.99         | \$10.99         | \$19.99         | \$28.99         | \$54.99         | \$99.99        | \$199.99         |
| products.product\_id.price\_raw                 | 3.99           | 10.99           | 19.99           | 28.99           | 54.99           | 99.99          | 199.99           |
| products.product\_id.price\_per\_day            | 0.57           | 0.37            | 0.33            | 0.32            | 0.30            | 0.27           | 199.99           |
| products.product\_id.price\_per\_week           | 3.99           | 2.75            | 2.50            | 2.41            | 2.29            | 1.92           | 199.99           |
| products.product\_id.price\_per\_month          | 15.96          | 10.99           | 9.99            | 9.66            | 9.17            | 8.33           | 199.99           |
| products.product\_id.price\_per\_year           | 207.48         | 131.88          | 119.94          | 115.96          | 109.98          | 99.99          | 199.99           |
| products.product\_id.currency\_symbol           | \$             | \$              | \$              | \$              | \$              | \$             | \$               |
| products.product\_id.currency\_code             | USD            | USD             | USD             | USD             | USD             | USD            | USD              |
| products.product\_id.period\_unit               | week           | month           | month           | month           | month           | year           | \*               |
| products.product\_id.period\_unit\_count        | 1              | 1               | 2               | 3               | 6               | 1              | -                |
| products.product\_id.periodly                   | weekly         | monthly         | 2 months        | 3 months        | 6 months        | annually       | lifetime         |
| products.product\_id.period\_iso                | P1W            | P1M             | P2M             | P3M             | P6M             | P1Y            | \*               |
| products.product\_id.trial\_period\_unit        | day            | week            | week            | week            | month           | month          | -                |
| products.product\_id.trial\_period\_unit\_count | 3              | 1               | 1               | 1               | 1               | 1              | \*               |
| products.product\_id.intro\_price               | \$2.99         | \$8.99          | \$17.99         | \$25.99         | \$49.99         | \$89.99        | -                |
| products.product\_id.intro\_period\_unit        | day            | week            | week            | week            | month           | month          | \*               |
| products.product\_id.intro\_period\_unit\_count | 3              | 1               | 1               | 1               | 1               | 1              | -                |

***

## Using Variables with Products

When adding variables, you can select which product context they apply to.

The dropdown in the variable picker lets you choose between:

* **Selected** – the product currently selected by user interaction (e.g., via “Select Product” action).
* **Specific product ID** – manually assign variables to monthly, annual, weekly, or custom product identifiers.

***

### Best Practices

* Always **[link products before using variables](product-setup-store-connection-1)** — otherwise, the picker won’t display sample data.
* Use `{{products.selected.price}}` for global CTAs (e.g., “Continue for \$4.99/month”).
* Combine trial and price variables to create clear, conversion-oriented text.
* Keep variables inside **Text** or **Heading** components for best layout control

***

### Example: Dynamic Pricing Message

```
Get {{products.selected.trial_period_unit_count}}-day free trial,
then {{products.selected.price_per_month}}{{products.selected.currency_symbol}}/month.
```

Output example:

> “Get 7-day free trial, then \$4.99/month.”

<Frame>
  <img />
</Frame>

***

[Properties Reference](properties-reference)

[Localization](ai-localization)


# watchOS/visionOS
Source: https://documentation.qonversion.io/docs/watchosvisionos

Install Qonversion SDK to implement in-app subscriptions, validate user receipts, get subscription analytics, and send subscription events to third-party integrations.

## Install SDK

Qonversion supports Cocoapods and Swift Package Manager to package your dependencies as a framework.

## Install via Cocoapods

Add dependency to `Podfile`.

<CodeGroup>
  ```text Podfile theme={null}
  pod 'Qonversion'
  ```
</CodeGroup>

Run `pod install` in the project directory to download the dependency.

<CodeGroup>
  ```bash Terminal theme={null}
  pod install
  ```
</CodeGroup>

## Install via Apple Swift Package Manager

Open Xcode, go to **File → Add Package Dependencies...** and enter the package URL `https://github.com/qonversion/qonversion-ios-sdk` in the search bar to import the package.

## Data sharing between iOS and watchOS

Please note that for our SDK to work correctly in the watchOS application (as well as when working with iOS Extensions), it is necessary to set up data sharing between iOS and watchOS applications so that we can identify the same user across both applications.

First, you need to enable data sharing between your app and shared extensions.

1. [Enable app groups](https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionScenarios.html#//apple_ref/doc/uid/TP40014214-CH21-SW1) for the containing app and extension via Xcode or the Developer portal. Choose your App target in Xcode. Select `Signing & Capabilities`, click `+ Capability` and select `App Groups`.
2. [Register the app group](https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW19) in the portal. In Xcode, add the new App Group ID.
3. Choose that App Group ID for the extension and containing app.
4. Pass user defaults instance created with a suite name to Qonversion via Qonversion.Configuration `setCustomUserDefaults()` function.

<CodeGroup>
  ```swift Swift theme={null}
  let config = Qonversion.Configuration(projectKey: "project_key", launchMode: .subscriptionManagement)
  ...
  // any other configurations
  ...
  config.setCustomUserDefaults(.init(suiteName: "app_groups_id_from_previous_step"))
  Qonversion.initWithConfig(config)
  ```

  ```objectivec Objective-C theme={null}
  QONConfiguration *configuration = [[QONConfiguration alloc] initWithProjectKey:@"project_key" launchMode:QONLaunchModeSubscriptionManagement];
  ...
  // any other configurations
  ...
  [configuration setCustomUserDefaults:[[NSUserDefaults alloc] initWithSuiteName:@"app_groups_id_from_previous_step"]];
  [Qonversion initWithConfig:configuration];
  ```
</CodeGroup>

After those steps, all content stored in the user defaults will be shared between the watchOS App and containing App.

***

[Kids Mode](kids-mode-sdk)

[Analytics Mode](analytics-mode)


# Web 1.+ migration guide
Source: https://documentation.qonversion.io/docs/web-1-migration-guide

Historical migration guide for upgrading the Qonversion Web SDK to major version 1.+: updated initialization, renamed methods, and revised purchase and entitlement APIs.

## Upgrading version

Increase the dependency version in your package.json file to upgrade your Qonversion SDK to the latest

<CodeGroup>
  ```json package.json theme={null}
  "@qonversion/web-sdk": "^1.0.0"
  ```
</CodeGroup>

## Renamings

In this major version, we have renamed several entities and public methods to make our namings more clear. To make everything work just change all the occurrences from the left column of the table below to the new ones.

| Before upgrade    | After upgrade     |
| ----------------- | ----------------- |
| `UserProperty`    | `UserPropertyKey` |
| `getEntitlements` | `entitlements`    |

## User properties changes

As mentioned above, we have renamed the`UserProperty` enum to `UserPropertyKey`. It was made to release the name `UserProperty` for a class, containing both the property key and its value. This class will be used in the new Qonversion method `userProperties`, which will return all the properties set for the current user.

<CodeGroup>
  ```javascript theme={null}
  try {
    const userProperties = await Qonversion.getSharedInstance().userProperties();
    userProperties.properties.forEach(userProperty => {
      console.log('User property - key:' + userProperty.key + ', value: ' + userProperty.value);
    });
  } catch (e) {
    // handle error here
  }
  ```
</CodeGroup>

`UserProperties` class returned as the successful result of `userProperties` contains several useful fields and methods to get all the types of properties you may want:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                 | Description                                                                                              |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `getProperty`        | `key` - string            | Searches for a property with the given property `key` in all properties list                             |
| `getDefinedProperty` | `key` - `UserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

The last change here is that we've enriched `UserPropertyKey` enum with a `Custom` key to represent all the custom properties.

***

[Cordova 4.+ migration guide](cordova-4-migration-guide)

[\[Dec 2022\] Migration Guide](migrate-to-the-actual-qonversion-sdk-version-december-2022)


# Web Funnel — Sell subscriptions on the web
Source: https://documentation.qonversion.io/docs/web-funnel

Build a web checkout funnel with the No-Code Builder and let users pay on the web (Stripe) and unlock the subscription in your mobile app.

A **Web Funnel** is a No-Code screen served on the web. Users open it in a browser (from ads, emails, or influencer links), pay with Stripe, and then unlock the subscription inside your mobile app through a redemption link.

Unlike Mobile Paywall / Mobile Onboarding screens (which render inside your app), a Web Funnel is hosted by Qonversion at `screens.qonversion.io` and checkout runs through **Stripe**.

## Prerequisites

* **Stripe connected** to your project: **Project Settings → Stores → Stripe → Connect Stripe** (Stripe OAuth — no API keys to paste). Web Funnels require Stripe; the Publish button stays disabled until Stripe is connected.
* A **product** mapped to a **Stripe Price ID** — set up below.
* A **Stripe webhook** with its signing secret added on the Stripe store card — see [Set up the Stripe webhook](#set-up-the-stripe-webhook).

### Map a product to a Stripe Price

The checkout charges a Stripe **Price** (`price_...`), not a Product (`prod_...`). Connect one to a Qonversion product:

1. In the Stripe Dashboard of your **connected** Stripe account (live mode), open **Product catalog → Add product**, set a **recurring** price, and save. (An existing product works too — every price lives on a product's page, in the **Pricing** section.)
2. Copy the **Price ID** — it looks like `price_...`.
3. In the Qonversion dashboard, open **Products** in the left menu and open the product you want to sell on the web (or create one — for subscriptions pick the matching duration).
4. Paste the Price ID into the **Stripe Price ID** field and save.

<Info>
  The price must live in the same Stripe account you connected to Qonversion — prices from any other account can't be resolved at checkout. Mobile store IDs (App Store / Play) on the same product are unrelated and can stay as they are.
</Info>

**Why a Price ID, when the Stripe integration never needed one?** With the classic Stripe integration *your own* checkout creates the subscription and picks the price — Qonversion only matches incoming webhook events to a product, and a `prod_...` id is enough for that. A Web Funnel flips this: **Qonversion runs the checkout for you**, and Stripe requires an exact Price to start a checkout session. A Stripe product can carry many prices (monthly, annual, currencies), so you pin the one to sell in the **Stripe Price ID** field.

## Set up the Stripe webhook

Qonversion records your web purchases by listening to events from your Stripe account — payment confirmations, subscription renewals, refunds. Every incoming event is verified with a **webhook signing secret** unique to your endpoint. Without it, purchase events can't be verified, and Web Funnel purchases won't reach your users.

Stripe keeps live and test traffic fully separate: a live-mode endpoint and a test-mode endpoint are **two different endpoints with two different signing secrets**. Qonversion mirrors this — the Stripe store card has a **Production webhook signing secret** field and, once you connect Stripe in sandbox, a separate **Sandbox webhook signing secret** field. This section sets up the production one; the sandbox secret is covered in [Test with a sandbox purchase](#test-with-a-sandbox-purchase).

You never share Stripe API keys (`sk_...`) with Qonversion — account access is granted through Stripe Connect, and the signing secret can only be used to verify that events are authentic. Anyone with access to the **Developers** section of your Stripe Dashboard can set this up.

### Step 1 — Create the webhook endpoint in Stripe

1. Open your [Stripe Dashboard](https://dashboard.stripe.com) → **Developers → Webhooks → Add endpoint** (in the newer Workbench UI: **Add destination → Webhook endpoint**).
2. If asked for the destination scope, choose **Your account** (not *Connected accounts*).
3. Set the endpoint URL to `https://api.qonversion.io/v1/stripe-s2s/`.
4. Select the following events:
   * `checkout.session.completed` — confirms the purchase *(required)*
   * `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted` — subscription lifecycle *(required)*
   * `invoice.paid` — renewals and trial conversions *(required)*
   * `charge.refunded` — refunds
   * `charge.dispute.created`, `charge.dispute.funds_withdrawn`, `charge.dispute.closed` — chargebacks
5. Create the endpoint.

<Info>
  Create this endpoint in **live mode** (Test mode toggle off) — it handles your production purchases. For sandbox testing you'll add a separate **test-mode** endpoint; see [Test with a sandbox purchase](#test-with-a-sandbox-purchase).
</Info>

### Step 2 — Add the signing secret to Qonversion

1. On the endpoint page in Stripe, click **Reveal** under **Signing secret** and copy the `whsec_...` value.
2. In the Qonversion dashboard, open **Project Settings → Stores** and on the **Stripe** card paste it into the **Production webhook signing secret** field, then save.

Qonversion validates the secret and checks that your Stripe connection is active. If you later roll the secret in Stripe, the dashboard shows a banner asking you to paste the refreshed value.

## 1. Create a Web Funnel

1. Go to **No-Codes → Create Screen**.
2. Choose **Web Funnel** as the screen type.
3. Design the screen in the Builder as usual (headings, products, buttons).
4. Add a **Product** component to the screen, then bind it: open **Settings → Products** in the Builder and pick your Stripe-priced product from the dropdown for the screen's product slot. This is what the checkout charges — a funnel without a Stripe-priced product cannot check out.
5. Set the purchase button's action to **Make a purchase**. On the web this opens the Stripe checkout for the bound product.
6. Add a **success page** the buyer sees after paying (this is also where you can remind them to open the redemption email).

<Info>
  A Web Funnel is served on the web, so a few in-app-only actions don't apply:

  * Navigation actions (`Navigate to the screen`) are no-ops on the web — use **Go to page** to move between funnel steps.
  * `Restore` is not supported on the web.
</Info>

## 2. Publish

Open the **Publish** dialog. The readiness checklist confirms the funnel is ready:

* **Stripe connected** — required (blocking).
* Success page and other checks — recommended.

On publish, Qonversion generates a **production key** (`prod_key`) and the public checkout URL:

```
https://screens.qonversion.io/flows/{prod_key}
```

Share this URL in your ads, emails, or landing pages.

## 3. The purchase → redemption flow

1. A user opens the funnel URL and completes the Stripe checkout. The **email field on the Stripe payment page** is where the buyer's address is collected — there is no separate email step; the redemption email goes to that address.
2. Qonversion emails them a one-time **redemption link** (`https://screens.qonversion.io/r/{project_uid}/{token}`).
3. The user taps the link on their phone → your app opens and the purchase is redeemed, activating the entitlement.

To handle the redemption link in your app, see **[Web Funnel — Redeem web purchases in your app](web-funnel-redemption)**.

## The redemption email

After a successful payment, Qonversion automatically sends the buyer a redemption email — you don't send anything yourself.

* **Trigger:** sent once, right after the payment is confirmed. The buyer enters their email during checkout.
* **Contents:** a call-to-action button and a fallback link to `https://screens.qonversion.io/r/{project_uid}/{token}`.
* **One-time & time-limited:** the link works **once** and expires **30 days** after purchase. After it's used (or expires), it can't be reused.
* **Lost or expired link:** the buyer can request a fresh one from your app, which sends a new email with a new link and a new 30-day window. See the [redemption guide](web-funnel-redemption#reissue-a-redemption-link).

<Info>
  **Sender & branding.** The email is currently sent from Qonversion. Per-merchant branding (your app's name / sender) is on the roadmap. If a buyer doesn't see the email, ask them to check spam.
</Info>

## Testing

### Test with a sandbox purchase

You can run the whole funnel end to end in Stripe **test mode** — no real charge — before going live.

1. **Connect Stripe in sandbox.** In **Project Settings → Stores** on the **Stripe** card, click **Connect Sandbox**. This is separate from your live connection and links your Stripe test account.
2. **Add a test-mode Stripe webhook.** Stripe keeps live and test events separate, so your live webhook won't receive sandbox purchases. In your [Stripe Dashboard](https://dashboard.stripe.com) with **Test mode on**, add a second endpoint at `https://api.qonversion.io/v1/stripe-s2s/` with the same events as your live endpoint (Step 1 above).
3. **Add the sandbox signing secret.** The test-mode endpoint has its own `whsec_...` signing secret — your production secret won't verify sandbox events. Reveal and copy it from the endpoint page in Stripe (Test mode on), then in **Project Settings → Stores** paste it into the **Sandbox webhook signing secret** field on the **Stripe** card. Without it, sandbox purchase events fail signature verification and test purchases won't reach your users.
4. **Open the sandbox link.** In the **Publish** dialog, below the production link, you'll find a **Sandbox** link:

   ```
   https://screens.qonversion.io/flows/sandbox/{sandbox_key}
   ```

   The same published funnel serves both URLs, so there's nothing extra to publish.
5. **Check out with a Stripe test card** — for example `4242 4242 4242 4242` (see [Stripe's test cards](https://docs.stripe.com/testing)). The checkout runs in Stripe test mode against your sandbox account, so no real money is charged.

A test purchase grants a **sandbox** entitlement, so your app must be running in the **sandbox** environment (`QEnvironment.Sandbox`) to see it after redeeming. Sandbox purchases never appear in your production revenue or analytics.

<Warning>
  Don't share the sandbox link with real customers — it only processes test payments and grants sandbox entitlements.
</Warning>

### Testing the redemption link on Android

You can test redemption with a debug build from Android Studio — on a real device or an emulator with Google Play services:

1. **Register the debug signing key.** Debug builds are signed with the debug keystore, and Android verifies App Links against the certificate of the installed build. Get the fingerprint with `./gradlew signingReport` (the `SHA-256` line under `Variant: debug`) and add it in **Connect Apps** — the fingerprints field accepts multiple values, so keep both your debug and release/Play App Signing keys there.
2. **Match the application ID.** If your debug build uses `applicationIdSuffix` (e.g. `.debug`), register the suffixed ID — otherwise verification won't match the installed package.
3. **Wait for the manifest, then (re)install.** After you add or change an app in Connect Apps, allow a few minutes for `https://screens.qonversion.io/.well-known/assetlinks.json` to refresh, then reinstall the app — Android checks App Links at install time. To force a re-check without reinstalling:

```bash theme={null}
adb shell pm verify-app-links --re-verify <your.package>
adb shell pm get-app-links <your.package>   # expect: screens.qonversion.io: verified
```

4. **Open a redemption link without the email.** You can fire the link straight from the terminal to check that it opens your app (not the browser):

```bash theme={null}
adb shell am start -a android.intent.action.VIEW \
  -d "https://screens.qonversion.io/r/{project_uid}/{token}"
```


# Web Funnel — Redeem web purchases in your app
Source: https://documentation.qonversion.io/docs/web-funnel-redemption

Let users who purchased on your web funnel unlock the subscription inside your mobile app via a redemption deep link. Grant-first: the entitlement is already granted server-side; the SDK just refreshes it.

A **Web Funnel** lets a user buy a subscription on the web (Stripe Checkout) and then unlock it inside your mobile app. After a successful purchase, Qonversion emails the buyer a one-time **redemption link**. When they tap it on their device, your app opens and the SDK redeems the purchase — activating the entitlement for that device.

This guide covers the mobile side: setting up the deep link and handling redemption in the Qonversion SDK.

<Info>
  **Grant-first model.** On a successful redemption the backend has **already granted** the entitlement to the app user. The SDK only **refreshes** the local entitlements — you do **not** need to call `identify()` or grant anything yourself.
</Info>

## How it works

1. The user completes a purchase on your published web funnel.
2. Qonversion sends a redemption email with a link of the shape:
   `https://screens.qonversion.io/r/{project_uid}/{token}`
3. The user taps the link on their phone → your app opens via a Universal Link (iOS) / App Link (Android).
4. Your app passes the link to the Qonversion SDK, which redeems the token and refreshes entitlements.

<Info>
  **Opened on desktop or without the app?** The same URL also serves a minimal **"Open in app"** fallback page (for desktop browsers, or if the Universal/App Link didn't auto-open). Visiting that page does **not** consume the token — it's only consumed when the app redeems it. So the link keeps working until the user opens it on a device with the app installed (within the 30-day window).
</Info>

## Before you start

* **Qonversion SDK installed and initialized** in your app. See [Install SDK](installation). Redemption works in the SDK's default Subscription Management mode.
* The device has a Qonversion user (the SDK creates one on launch). Redemption grants the entitlement to **this** device's user — there's nothing to identify manually.

## Prerequisites

Before redemption links can open your app, register your app in the Qonversion Dashboard so Qonversion can serve the association files (`apple-app-site-association` / `assetlinks.json`) for `screens.qonversion.io`:

**Dashboard → Project Settings → Connect Apps** — add your app:

* **iOS:** Bundle ID + Apple Team ID
* **Android:** Package name + signing certificate **SHA-256** fingerprint

Qonversion generates the association files automatically from these values. No manual file hosting is required.

## Step 1 — Register the deep link

The redemption link uses the shared host `screens.qonversion.io`, and the path is scoped to **your** project: `/r/{project_uid}/{token}`. You can find your `project_uid` in the Dashboard (Connect Apps).

<Warning>
  **iOS and Android differ here**

  * **iOS** — you register only the **domain**; Qonversion scopes the path to your project server-side.
  * **Android** — you must register the **path scoped to your `project_uid`**. Because the domain is shared across all Qonversion merchants, a generic `/r/*` filter would clash with other Qonversion-powered apps on the device. Scoping to your `project_uid` prevents that.
</Warning>

### iOS — Associated Domains

Add the Associated Domains capability with:

```
applinks:screens.qonversion.io
```

### Android — App Links

Add an intent filter to the activity that should handle redemption, scoped to your `project_uid`:

```xml AndroidManifest.xml theme={null}
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
        android:scheme="https"
        android:host="screens.qonversion.io"
        android:pathPattern="/r/YOUR_PROJECT_UID/.*" />
</intent-filter>
```

Replace `YOUR_PROJECT_UID` with your project's uid from the Dashboard.

## Step 2 — Handle the redemption link

Forward the incoming URL to `handleRedemptionLink`. The SDK validates the host and path internally before making any network call.

<CodeGroup>
  ```swift Swift theme={null}
  // SwiftUI — forward the Universal Link
  .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
      guard let url = activity.webpageURL else { return }
      Qonversion.shared().handleRedemptionLink(url: url) { result in
          switch result {
          case .success:
              print("Entitlements refreshed")
          case .tokenExpired, .alreadyConsumed, .invalidToken:
              print("Redemption not completed: \(result)")
          case .networkError, .retryable:
              print("Temporary error — try again")
          @unknown default:
              break
          }
      }
  }
  ```

  ```objectivec Objective-C theme={null}
  // UIKit — scene:continueUserActivity: / application:continueUserActivity:
  [[Qonversion sharedInstance] handleRedemptionLink:url completion:^(QONRedemptionResult result) {
      if (result == QONRedemptionResultSuccess) {
          NSLog(@"Entitlements refreshed");
      }
  }];
  ```

  ```kotlin Kotlin theme={null}
  // Android — in the activity that receives the App Link
  override fun onNewIntent(intent: Intent) {
      super.onNewIntent(intent)
      val uri = intent.data ?: return
      Qonversion.shared.handleRedemptionLink(uri, object : QonversionRedemptionCallback {
          override fun onResult(result: RedemptionResult) {
              when (result) {
                  RedemptionResult.Success -> { /* entitlements refreshed */ }
                  RedemptionResult.TokenExpired,
                  RedemptionResult.AlreadyConsumed,
                  RedemptionResult.InvalidToken -> { /* not completed */ }
                  RedemptionResult.NetworkError,
                  RedemptionResult.Retryable -> { /* temporary — retry */ }
              }
          }
      })
  }
  ```
</CodeGroup>

<Warning>
  Do not call `identify()` after a successful redemption. The entitlement is already granted to the user on the backend; the SDK refreshes it for you. Adding your own `identify()` is unnecessary and may cause an extra network round-trip.
</Warning>

## Redemption results

| Result            | Meaning                                                   | Suggested handling                                                       |
| :---------------- | :-------------------------------------------------------- | :----------------------------------------------------------------------- |
| `Success`         | Entitlement granted and refreshed.                        | Continue into the app's paid experience.                                 |
| `TokenExpired`    | The link's TTL elapsed (30 days by default).              | Offer to reissue the link (see below).                                   |
| `AlreadyConsumed` | The link was already redeemed.                            | Inform the user; the purchase is already active on the redeeming device. |
| `InvalidToken`    | Malformed / unknown token.                                | Show a generic error.                                                    |
| `NetworkError`    | The device could not reach the server.                    | Ask the user to retry.                                                   |
| `Retryable`       | The server returned a transient error (rate limit / 5xx). | Retry later.                                                             |

## Reissue a redemption link

If the original link expired or was lost, let the user request a fresh one by email. The two platforms expose this differently:

* **iOS** — your app collects the email and passes it to `reissueRedemption(email:)`.
* **Android** — the SDK presents a ready-made dialog that collects the email for you via `presentReissueUI(activity:)`.

<CodeGroup>
  ```swift Swift theme={null}
  Qonversion.shared().reissueRedemption(email: email) { success, statusCode, error in
      // success == a new redemption email was accepted for sending
  }
  ```

  ```kotlin Kotlin theme={null}
  // The SDK shows a dialog that collects the email and requests the new link.
  Qonversion.shared.presentReissueUI(activity) { success ->
      // success == a new redemption email was accepted for sending
  }
  ```
</CodeGroup>

<Info>
  A successful/accepted result means the request was **accepted**, not that a matching purchase exists or that the mail was delivered — the backend intentionally responds uniformly so the endpoint can't be used to probe which emails have purchases.
</Info>


# Web SDK
Source: https://documentation.qonversion.io/docs/web-sdk

Send Web purchases data to manage cross-platform user access: Web, iOS, Android.

[![GitHub release](https://img.shields.io/github/v/release/qonversion/web-sdk?label=Latest%20Release)](https://github.com/qonversion/web-sdk/releases)

## Install

Qonversion SDK package is available on [npm](https://www.npmjs.com/package/@qonversion/web-sdk).

<CodeGroup>
  ```shell npm theme={null}
  npm install @qonversion/web-sdk
  ```

  ```shell Yarn theme={null}
  yarn add @qonversion/web-sdk
  ```
</CodeGroup>

You can check the implementation details of the Web SDK [here](https://github.com/qonversion/web-sdk).

## Launching the SDK

First of all, you need to create the launching configuration. It can be made using the `QonversionConfigBuilder` class as follows.

<CodeGroup>
  ```javascript theme={null}
  import {QonversionConfigBuilder} from '@qonversion/web-sdk';

  ...

  const config = new QonversionConfigBuilder(projectKey).build();
  ```
</CodeGroup>

You can also provide additional configuration if necessary.

<CodeGroup>
  ```javascript theme={null}
  import {Environment, LogLevel, QonversionConfigBuilder} from '@qonversion/web-sdk';

  ...

  const config = new QonversionConfigBuilder(projectKey)
    .setLogLevel(LogLevel.Verbose) // The lower level you set the more logs will be written
    .setLogTag('CustomLogTagForMyApp') // Will be added to all Qonversion logs.
    .build();
  ```
</CodeGroup>

After the configuration is prepared, you should initialize the SDK using it.

<CodeGroup>
  ```javascript theme={null}
  import Qonversion from '@qonversion/web-sdk';

  ...

  const qonversionInstance = Qonversion.initialize(config);
  ```
</CodeGroup>

Now you are ready to use the SDK. All the work with the SDK is done via the initialized instance.

<CodeGroup>
  ```javascript theme={null}
  const entitlements = await qonversionInstance.entitlements();

  // or if you don't want to store and transport created instance between 
  // different layers of your architecture, you can use Qonversion shared instance:
  const qonversionInstance = Qonversion.getSharedInstance();
  const entitlements = await qonversionInstance.entitlements();
  ```
</CodeGroup>

Make sure you have called `Qonversion.initialize()` before you call `Qonversion.getSharedInstance()` as it will throw an Error if no instance is configured.

Note that some configurations can be changed after the initialization, but we recommend setting everything necessary before it. Nonetheless, if you want to change, let's say, the log tag of the configured instance, call the corresponding method on it.

<CodeGroup>
  ```javascript theme={null}
  qonversionInstance.setLogTag('NewCustomLogTagForMyApp');
  ```
</CodeGroup>

## Properties

User properties are attributes you can set on a user level. You can send user properties to third-party platforms and use them in Qonversion for customer segmentation and analytics. You can read more about user properties [here](user-properties).

We defined some common case properties and provided API for adding them:

<CodeGroup>
  ```javascript theme={null}
  import {UserPropertyKey} from '@qonversion/web-sdk';

  ...

  qonversionInstance.setUserProperty(UserPropertyKey.CustomUserId, 'yourSideUserId');
  ```
</CodeGroup>

You can also provide custom properties using the following method.

<CodeGroup>
  ```javascript theme={null}
  qonversionInstance.setCustomUserProperty('liked-app', 'yes');
  ```
</CodeGroup>

If you need to set several properties, you can call the above methods multiple times or use the `UserPropertiesBuilder` class, which provides a well-known builder pattern for combining properties. After you have set all the necessary properties, you can send them to Qonversion with a single call of the following method.

<CodeGroup>
  ```javascript theme={null}
  import {UserPropertiesBuilder} from '@qonversion/web-sdk';

  ...

  const properties = new UserPropertiesBuilder()
    .setCustomUserId('yourSideUserId')
    .setEmail('[email protected]')
    .setCustomUserProperty('liked-app', 'yes')
    .build();

  qonversionInstance.setUserProperties(properties);
  ```
</CodeGroup>

To get all the properties set to a user, you can call the `userProperties` method, that returns an object, containing all the properties.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const userProperties = await Qonversion.getSharedInstance().userProperties();
  userProperties.properties.forEach(userProperty =>
    console.log('Property key: ' + userProperty.key + ', value: ' + userProperty.value)
  );
  ```
</CodeGroup>

The return `UserProperties` class contains several utility fields and methods:

| Field                      | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `properties`               | List of all user properties                                                 |
| `definedProperties`        | Subset of all user properties, which were set using Qonversion-defined keys |
| `customProperties`         | Subset of all user properties, which were set using custom keys             |
| `flatPropertiesMap`        | A flattened version of all user properties as a key-value map               |
| `flatDefinedPropertiesMap` | A flattened version of defined user properties as a key-value map           |
| `flatCustomPropertiesMap`  | A flattened version of custom user properties as a key-value map            |

| Method               | Arguments                 | Description                                                                                              |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `getProperty`        | `key` - string            | Searches for a property with the given property `key` in all properties list                             |
| `getDefinedProperty` | `key` - `UserPropertyKey` | Searches for a property with the given Qonversion-defined property `key` in the defined properties list. |

## Purchases

Qonversion Web SDK accepts [Stripe](stripe-integration) and [Paddle](paddle-integration) purchases. We are working on supporting more billing providers. To send the purchase to Qonversion after you receive a successful response from your billing provider, call the matching method and provide the received data.

<CodeGroup>
  ```javascript Stripe theme={null}
  const purchase = await qonversionInstance.sendStripePurchase(stripeData);
  ```

  ```javascript Paddle theme={null}
  // Fields are camelCase; use type 'inapp' for one-time purchases.
  const purchase = await qonversionInstance.sendPaddlePurchase({
    price: '9.99',
    currency: 'USD',
    transactionId: 'txn_01hv4rrk',
    productId: 'pro_01hv4rrk',
    type: 'subscription',           // or 'inapp' for one-time purchases
    subscriptionId: 'sub_01hv4rrk', // required for 'subscription'; omit for 'inapp'
  });
  ```
</CodeGroup>

Once you have successfully sent a purchase, request the updated user entitlements using the method described below and grant a user the necessary access.

## Entitlements

To let Qonversion handle user entitlements, you should configure them in the [Qonversion dashboard](subscription-management-mode#1-configure-products--entitlements) first. After you have it done, Qonversion will grant entitlements to the current user each time you send us a successful purchase. Then you can get the current user entitlements as follows.

<CodeGroup>
  ```javascript theme={null}
  const entitlements = await qonversionInstance.entitlements();
  ```
</CodeGroup>

## Identity

User Identity allows cross-device & cross-platform user identification and access management. You can read more about it [here](user-identifiers#3-user-identity).

When a user logs into his account, call `identify()`.

<CodeGroup>
  ```javascript theme={null}
  await qonversionInstance.identify('your_custom_user_id');
  ```
</CodeGroup>

And when a user logs out call `logout()`

<CodeGroup>
  ```javascript theme={null}
  await qonversionInstance.logout();
  ```
</CodeGroup>

Consider looking at the examples [here](user-identifiers#examples) to better understand `identify()` at work.

***

## Next steps

The Web SDK is set up. Connect a billing provider and manage cross-platform access. Start by wiring up [Stripe](stripe-integration) or [Paddle](paddle-integration) and mapping their products into your Qonversion [entitlements](entitlements).

<NextStepsSubscription />


# Webhooks
Source: https://documentation.qonversion.io/docs/webhooks

Send in-app subscription and purchase events to your server with webhooks

Qonversion validates user receipts with app stores and sends subscription events to your HTTP endpoints. Keep in mind events delivery time when using webhooks to manage subscriber statuses on your back-end. Webhook delivery is asynchronous and typically completes within tens of seconds, but the exact latency depends on store-side notification timing, your server's response time, and any retries. For real-time subscription status on the client-side, use the [checkEntitlements](check-permissions) method of the Qonversion SDK.

## 1. Set up the webhook URL

1. Navigate to the Integrations section in your Qonversion account and select Webhooks.
2. Register your URL and Qonversion will send a request
3. Press the "Add new integration" or "Save" button. If the endpoint server returns a 200 response code, the integration is activated.

<img alt="" />

### Sandbox webhook URL

The Webhooks integration form also exposes a separate **Sandbox Webhook URL** field. Production-environment events are delivered to the main URL; sandbox-environment events (`environment: "sandbox"`) are delivered to the Sandbox URL when it is set. If you receive sandbox events but leave the Sandbox URL empty, Qonversion will fail to deliver them and they will be retried until the per-event tracking window expires.

## 2. Request format

Qonversion sends **POST** request to webhook URL every time an event occurs. The request includes an `Authorization` header of the form `Basic <token>`, where `<token>` is the **Header Authorization-Token Value** you configured in the Webhooks integration settings - it is sent as-is, not base64-encoded as in standard HTTP Basic auth. Use it to protect your server from unwanted requests.

<Info>
  ### SSL certificate

  Remember, maintaining secure connections is essential for the integrity and reliability of your application's communication.

  Ensure the SSL certificate used is not expired and your server's CA bundle is up-to-date to recognize the latest root CAs.
</Info>

**Request Header:**

<CodeGroup>
  ```json theme={null}
  Authorization: Basic {Header Authorization-Token}
  Accept: application/json
  ```
</CodeGroup>

**Request Body:**

<CodeGroup>
  ```json theme={null}
  {
      "event_name": "trial_converted",
      "user_id": "3YjIDEUDaf_5g4IdWw6zcMlLgfg_YQp2",
      "custom_user_id": "",
      "identity_id": "",
      "advertiser_id": "9FD1767D-8B48-45BD-A2F4-1C08B08E56F2",
      "time": 1600000000,
      "created_at": 1600000000,
      "product_id": "com.myapp.subs.9.99.trial",
      "revenue": {
          "value": 7.99,
          "value_usd": 9.99,
          "currency": "GBP",
          "is_proceed": 0,
          "proceeds_rate": 70
      },
      "price": {
          "value": 7.99,
          "value_usd": 9.99,
          "currency": "GBP"
      },
      "transaction": {
          "transaction_id": "500000601234560",
          "original_transaction_id": "500000601234560",
          "expires": 1600259200,
          "grace_period_expires": null,
        "transaction_date": 1600004000,
  			"promo_offer_id": "appname.subscription.month.withoutTrial.promo"

      },
      "properties": {
          "_q_email": "me@qonversion.io"
      },
      "device_id": "0E66565D-4F3A-E366-B3D4-B5DDAC6BBE2E",
      "app_version": "2.1.4",
      "sdk_version": "3.1.0",
      "environment": "production",
      "platform": "iOS",
      "ip": "10.0.0.1",
      "country": "GB",
      "storefront": "GBR",
      "old_product_id": "com.myapp.subs.4.99.trial",
      "new_product_id": "com.myapp.subs.9.99.trial",
      "locale": "en_US",
      "subscription_group": "784563",
      "user_install_date": 1600000000,
      "project_name": "Sample App",
      "app_id": "com.sample.app",
      "quantity": 3,
      "subscription_renew_count": 5,
      "billing_plan_type": "monthly",
      "commitment": {
          "installment_number": 3,
          "total_installments": 12,
          "expires_at": 1790000000,
          "total_price": 119.88
      },
      "entitlements": [
          {
              "active": true,
              "expires": 1654215637,
              "id": "plus",
              "product": {
                  "product_id": "main",
                  "subscription": {
                      "current_period_type": "regular",
                      "renew_state": "will-renew"
                  }
              },
              "source": "stripe",
              "started": 1652438020
          }
      ],
      "asa_attribution": {
          "org_id": 1234567890,
          "campaign_id": 1234567890,
          "adgroup_id": 1234567890,
          "keyword_id": 1234567890,
          "ad_id": 1234567890,
          "country_or_region": "DE",
          "conversion_type": "Download",
          "click_date": "2024-08-21T16:10Z",
   		   	"impression_date": "2024-08-21T16:10Z",
      		"claim_type": "Impression"
      }
  }
  ```
</CodeGroup>

<Note>
  `billing_plan_type` and `commitment` are present only for Apple 12-month-commitment
  subscriptions, available on iOS 26.4 and later. Such a subscription's period stays **yearly**
  while it is billed in twelve monthly installments, so `revenue` and `price` on this event hold
  the **monthly** installment, not the yearly amount. The monthly amounts alone give no hint that
  the subscription is yearly — `billing_plan_type` and `commitment` are the only way to tell an
  installment apart from an ordinary monthly subscription. Commitment plans billed other than in
  monthly installments are not currently reported.
</Note>

| Column                     | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| event\_name                | yes      | Event name provided in the integration config. See the details on the events tracked[here](integrations-overview)                                                                                                                                                                                                                                                                                                                         |
| user\_id                   | yes      | Unique user identifier assigned by Qonversion                                                                                                                                                                                                                                                                                                                                                                                             |
| custom\_user\_id           | yes      | Unique user identifier that you can set with Qonversion SDK methods:[User Identifiers](user-identifiers#logging-in)                                                                                                                                                                                                                                                                                                                       |
| identity\_id               | yes      | Unique user ID for the authenticated users that you can set using [identify method](user-identifiers#3-user-identity) of the Qonversion SDK                                                                                                                                                                                                                                                                                               |
| advertiser\_id             | yes      | IDFA or AAID                                                                                                                                                                                                                                                                                                                                                                                                                              |
| time                       | yes      | The time an app store changed a subscription status or a time Qonversion detected the change in the UNIX epoch time format in seconds. Read more about events time[here](integrations-overview#event-time)                                                                                                                                                                                                                                |
| created\_at                | yes      | The time Qonversion generated the event                                                                                                                                                                                                                                                                                                                                                                                                   |
| product\_id                | yes      | App Store or Google Play Store product identifier                                                                                                                                                                                                                                                                                                                                                                                         |
| revenue                    | yes      | Dictionary with transaction revenue details. Only events with value filled                                                                                                                                                                                                                                                                                                                                                                |
| price                      | yes      | Dictionary containing the price details of the product                                                                                                                                                                                                                                                                                                                                                                                    |
| transaction                | yes      | Dictionary with store transaction IDs and expiration timestamp                                                                                                                                                                                                                                                                                                                                                                            |
| properties                 | yes      | User properties provided by SDK as a JSON object (always present; sent as `{}` when the user has no properties). Read more about user properties [here](user-properties).                                                                                                                                                                                                                                                                 |
| device\_id                 | yes      | identifierForVendor or Settings Secure Android ID.                                                                                                                                                                                                                                                                                                                                                                                        |
| app\_version               | no       | Application version.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| sdk\_version               | no       | Qonversion SDK version.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| environment                | yes      | "production" or "sandbox".                                                                                                                                                                                                                                                                                                                                                                                                                |
| platform                   | yes      | "iOS", "Android", or "Stripe".                                                                                                                                                                                                                                                                                                                                                                                                            |
| ip                         | yes      | Application device IP address.                                                                                                                                                                                                                                                                                                                                                                                                            |
| country                    | yes      | A two-letter code representing a country, defined by the[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)standard, is determined on the Cloud provider's side based on the IP address of the incoming request.                                                                                                                                                                                                       |
| storefront                 | no       | Apple App Store country code ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3), e.g. "CHN", "USA", "GBR"). Represents the storefront from which the transaction originated. Not the user's geographic location. Only available for iOS transactions when an App Store Connect API Certificate is configured.                                                                                                        |
| old\_product\_id           | no       | Previous product (for product change events).                                                                                                                                                                                                                                                                                                                                                                                             |
| new\_product\_id           | no       | New product (for product change events).                                                                                                                                                                                                                                                                                                                                                                                                  |
| locale                     | yes      | A two-letter code representing a device language based on the device locale.                                                                                                                                                                                                                                                                                                                                                              |
| subscription\_group        | yes      | `subscription_group_identifier` for iOS or Google `base_plan_id` for Android. Empty string for Stripe events.                                                                                                                                                                                                                                                                                                                             |
| user\_install\_date        | yes      | Timestamp when the user last installed the application.                                                                                                                                                                                                                                                                                                                                                                                   |
| project\_name              | yes      | The project name of your app from the Qonversion dashboard.                                                                                                                                                                                                                                                                                                                                                                               |
| app\_id                    | yes      | Store App Id. App Store ID for iOS or Android Package Name for Android.                                                                                                                                                                                                                                                                                                                                                                   |
| quantity                   | no       | Number of consumable in-app purchases. For non-consumable items or subscriptions, it will always return 1. Only present when the event has an associated transaction.                                                                                                                                                                                                                                                                     |
| subscription\_renew\_count | no       | Total number of times a user's subscription has been renewed. Only present for events that carry a renewal counter (e.g. subscription renewals).                                                                                                                                                                                                                                                                                          |
| billing\_plan\_type        | no       | Billing plan of an Apple 12-month-commitment subscription. Always `monthly`: the commitment is charged in twelve monthly installments while the subscription period stays yearly. Present only for commitment subscriptions on iOS 26.4 and later.                                                                                                                                                                                        |
| commitment                 | no       | Apple 12-month-commitment details: `installment_number` and `total_installments` give this charge's position in the commitment (for example, 3 of 12); `expires_at` is the commitment end date as a Unix timestamp in seconds; `total_price` is the price of the whole commitment in major units of the currency reported by `price.currency` / `revenue.currency`. Individual keys are omitted when Apple does not provide their values. |
| entitlements               | yes      | Granted user entitlements. Always present, delivered as a JSON array (`[{...}, {...}]`) when the user has entitlements; sent as `{}` when the user has no active entitlements. Entity fields are synchronised with our [public API](/reference/overview).                                                                                                                                                                                 |
| asa\_attribution           | no       | Dictionary with Apple Search Ads attribution details. Only for events for users who were attributed with the ad.                                                                                                                                                                                                                                                                                                                          |

## Revenue and price fields

There are 3 fields that contain transaction details:

* The `revenue` field contains a dictionary with details depending on your integration setting *Send sales as proceed*.
* The `price` field always contains a gross price that is charged to a user.
* The `transaction` field contains params of the transaction related to the event.

### Revenue

| Column         | Required | Description                                                                                                                        |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| value          | yes      | Value in user's currency                                                                                                           |
| value\_usd     | yes      | Value in USD                                                                                                                       |
| currency       | yes      | Three-letter ISO currency code                                                                                                     |
| is\_proceed    | yes      | 1 – if `value` and `value_usd` are net excluding app stores' commission; 0 - if values are before deducting app stores commission; |
| proceeds\_rate | yes      | 70 or 85; Proceeds rate that developer receives after deducting app stores commission.                                             |

### Price

| Column     | Required | Description                    |
| ---------- | -------- | ------------------------------ |
| value      | yes      | Value in user's currency       |
| value\_usd | yes      | Value in USD                   |
| currency   | yes      | Three-letter ISO currency code |

### Transaction

| Column                    | Required | Description                                                                                                    |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| transaction\_id           | yes      | Transaction\_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)            |
| original\_transaction\_id | yes      | Transaction\_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)            |
| expires                   | yes      | Expire timestamp for purchase, prolong or product change events, event timestamp for refund or upgrade events. |
| grace\_period\_expires    | yes      | Grace period expiration timestamp. This field returns the timestamp for the grace period expiration.           |
| transaction\_date         | yes      | Timestamp when the transaction was made.                                                                       |

<Warning>
  For the **Billing Issue**, **Trial Canceled**, **Subscription Canceled**, **Subscription Upgraded** events, the `transaction_id` field will be the same as for the previous related event. For the **Subscription Renewed**, **Subscription Downgraded**, **Subscription Product Changed** events, we're sending a newer `transaction_id`.
</Warning>

## Apple Search Ads attribution fields

You need to set up [Apple Search Ads integration](apple-search-ads) first, then we will send ASA attribution with all new events for only attributed users. The data in the table below can be found in the `asa_attribution` field.

<CodeGroup>
  ```json json theme={null}
  {
    ...
    "asa_attribution": {
      "org_id": 1234567890,
      "campaign_id": 1234567890,
      "adgroup_id": 1234567890,
      "keyword_id": 1234567890,
      "ad_id": 1234567890,
      "country_or_region": "DE",
      "conversion_type": "Download",
      "click_date": "2024-08-21T16:10Z",
      "impression_date": "2024-08-21T16:10Z",
      "claim_type": "Impression"
    }
  }
  ```
</CodeGroup>

| Column              | Required | Description                                                                                                                                              |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| org\_id             | yes      | The identifier of the Organization or Campaign group Id that owns the campaign.                                                                          |
| campaign\_id        | yes      | The unique identifier for the campaign.                                                                                                                  |
| adgroup\_id         | yes      | The identifier for the ad group.                                                                                                                         |
| keyword\_id         | no       | The identifier for the keyword.                                                                                                                          |
| ad\_id              | yes      | The identifier representing the assignment relationship between an ad object and an ad group.                                                            |
| country\_or\_region | yes      | The country or region for the campaign.                                                                                                                  |
| conversion\_type    | yes      | The type of conversion is either Download or Redownload.                                                                                                 |
| click\_date         | no       | The date and time when the user clicks an ad in a corresponding campaign. Available only if a user accepts App Tracking Transparency (ATT).              |
| impression\_date    | no       | The date and time when an ad view occurs in a corresponding Apple Search Ads campaign. Available only if a user accepts App Tracking Transparency (ATT). |
| claim\_type         | no       | The type of claim is either Impression or Click.                                                                                                         |

Learn more about fileds from [Apple AdSevices documentation](https://developer.apple.com/documentation/adservices/aaattribution/attributiontoken\(\)#Attribution-payload-descriptions).

## Retries between Qonversion and Destination Server

Qonversion increases the delivery rate to your server with retries. Retries happen automatically if your server is not responding (returns a non-2xx status, times out, or is unreachable). This substantially improves the data delivery rate. After the initial attempt fails, Qonversion schedules up to five retries spread over roughly 24 hours, then abandons the per-event delivery job. The tracking record itself is retained for 7 days.

Retries have the following schedule (delay measured from the previous attempt):

| Attempt | Delay since previous | Approx. time since first attempt |
| ------- | -------------------- | -------------------------------- |
| 1       | Immediate            | 0                                |
| 2       | 1 minute             | \~1 minute                       |
| 3       | 5 minutes            | \~6 minutes                      |
| 4       | \~3 hours 55 minutes | \~4 hours                        |
| 5       | 4 hours              | \~8 hours                        |
| 6       | 16 hours             | \~24 hours                       |

***

[Tenjin](tenjin)

[Refund Keeper](refund-keeper)


# API v3 (legacy)
Source: https://documentation.qonversion.io/reference/overview

Legacy: the v3 REST API is superseded by API v4. This page summarizes v3 concepts, authentication keys, and a resource-to-v4 mapping for existing integrations. New integrations should use v4.

<Warning>
  **API v3 is legacy. Use [API v4](/reference/v4/overview) for all new integrations.** The v3 read endpoints remain available for existing integrations, but no new functionality is added to v3. This page consolidates the v3 concepts previously spread across separate reference pages. The full v3 operation reference lives in the **REST API v3** section of the [API Reference](/api-reference/users/retrieve-a-user) tab.
</Warning>

## Base URL

All v3 requests are made to:

```
https://api.qonversion.io/v3
```

Requests must include an `Authorization` header with a Bearer token and, for `POST`/`PUT`/`PATCH`/`DELETE` requests, a `Content-Type: application/json` header. Responses are JSON-encoded.

## Authentication: Project Key vs Secret Key

Both keys are found under **Project Settings** in the [Qonversion dashboard](https://dash.qonversion.io). The v3 API uses two Bearer tokens with different privileges:

| Key             | Prefix                          | Used for                                                                                                                                |
| --------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Project Key** | none (sandbox keys use `test_`) | Standard requests: retrieve/create users, properties, identities; retrieve entitlements; retrieve/create products; **record purchases** |
| **Secret Key**  | `sk_`                           | Access-modifying operations: **grant / revoke entitlements**                                                                            |

<Warning>
  The Secret Key must only be stored on your server. **Never embed it in Android, iOS, or web app code.**
</Warning>

Project Keys with the `test_` prefix (for example `test_PV77YHL7qnGvsdmpTs7gimsxUvY-Znl2`, the sample app key used in examples) target the **sandbox** environment; production keys have no prefix. There is also a separate **API Key** used only in the URL path of the Analytics API — it is not a v3 Bearer token.

## Key concepts

* **Qonversion User ID** — Auto-generated identifier prefixed with `QON_` (for example `QON_7791a27fc4e747412381842b36a`), created by the SDK on first launch. It is the primary key for all v3 user operations.
* **Environment** — Every user belongs to either `prod` or `sandbox`. Sandbox users do not affect production analytics.
* **Identity** — Links a Qonversion User ID to your own auth system's user ID, enabling cross-platform entitlement sharing. On another device, calling `identify()` with the same identity ID restores the user's entitlements.
* **User Properties** — Key-value attributes for segmentation, analytics filtering, and integrations. Qonversion-defined keys are prefixed with `_q_` (for example `_q_email`, `_q_appsflyer_user_id`); any other key is a custom property. See the [User Properties guide](/docs/properties-reference) for the full list of defined keys.
* **Entitlement** — An access right to premium features. Purchases grant entitlements automatically; you can also grant/revoke them via the API. An entitlement's `source` is one of `appstore`, `playstore`, `stripe`, `paddle`, `manual`, or `unknown`.
* **Purchase** — The v3 purchase endpoint records web/manual purchases: the request carries exactly one of `stripe_store_data`, `paddle_store_data`, `app_store_data`, or `play_store_data`. Stripe and Paddle are the typical paths; App Store and Google Play data are also accepted, though native purchases are normally recorded automatically by the SDK.
* **Product** — Represents an in-app purchase or subscription configured in the dashboard, linked to store-specific identifiers (Apple, Google, Stripe). A product's `type` is an integer enum `0`–`3` (`0` = Subscription With Promo Period, `1` = Regular Subscription, `2` = Non-Recurring / Consumable, `3` = Non-Consumable / Lifetime) and its `duration` is `0`–`4` (`0` = Weekly, `1` = Monthly, `2` = Three Monthly, `3` = Six Monthly, `4` = Annual).

## HTTP status & error codes

v3 uses standard HTTP status codes: `200` success, `201` created, `204` no content, `400` bad request, `401` invalid key, `403` secret key required, `404` not found, `422` logical error, `5xx` server error. Every error response shares a consistent envelope with an `error` object (`type` one of `request`, `resource`, `logical`, `internal`, plus a `code` and `message`) and a `_meta` object with a `reference` URL and field-level validation `fields`.

The `error.code` values by type:

| Type       | Code                   | Meaning                                                     |
| ---------- | ---------------------- | ----------------------------------------------------------- |
| `request`  | `invalid_data`         | Validation failed; see `_meta.fields` for details           |
| `request`  | `invalid_request`      | Unrecognized request URL                                    |
| `request`  | `control_unauthorized` | Authorization required                                      |
| `request`  | `not_implemented`      | Functionality at the requested address is not implemented   |
| `resource` | `not_found`            | Requested resource not found                                |
| `resource` | `already_exists`       | Requested resource already exists                           |
| `logical`  | `purchase_fraud`       | Could not validate purchase with the store, potential fraud |
| `logical`  | `relation_not_found`   | Nested objects could not be found or associated             |
| `internal` | `storage_error`        | Data was not saved                                          |
| `internal` | `network_error`        | Internal services interaction failed                        |
| `internal` | `unknown_error`        | Unknown reason                                              |

## Resource → v4 equivalent

Each v3 resource has a v4 successor. Prefer v4 for new work; the v3 operation schemas remain in the **REST API v3** section of the API Reference tab.

| v3 resource     | v4 equivalent                                             | v3 spec (API Reference)                                                             |
| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Users           | [Users (v4)](/reference/v4/users)                         | [Retrieve a user](/api-reference/users/retrieve-a-user)                             |
| User Properties | [User Properties (v4)](/reference/v4/user-properties)     | [Retrieve user properties](/api-reference/user-properties/retrieve-user-properties) |
| Identity        | [Identities (v4)](/reference/v4/identities)               | [Retrieve an identity](/api-reference/identity/retrieve-an-identity)                |
| Entitlements    | [Entitlements (v4)](/reference/v4/entitlements)           | [Retrieve entitlements](/api-reference/entitlements/retrieve-entitlements)          |
| Purchases       | [Purchases (v4)](/reference/v4/purchases)                 | [Create a purchase](/api-reference/purchases/create-a-purchase)                     |
| Products        | [Products (v4)](/reference/v4/products)                   | [List products](/api-reference/products/list-products)                              |
| Authentication  | [Authentication (v4)](/reference/v4/authentication)       | —                                                                                   |
| Handling errors | [Handling Errors (v4)](/reference/v4/handling-api-errors) | —                                                                                   |


# Analytics
Source: https://documentation.qonversion.io/reference/v4/analytics

Expose Qonversion dashboard data via the v4 API: charts, KPIs, cohorts, LTV curves, and AI-written narrative insights.

The **Analytics API** exposes the same data that powers the Qonversion dashboard: time-series charts, KPI cards, cohort tables, LTV curves, and narrative insights. Every endpoint supports filtering by currency, date range, and segment where applicable.

## Key concepts

* **Chart codes** — Stable string identifiers for each chart. 25 public codes covering revenue (`proceeds`, `sales`, `refunds`, `refund-rate`, `arpu`, `arppu`), recurring revenue (`mrr`, `arr`, `mrr-movement`, `arr-movement`), subscriptions (`active-subscriptions`, `new-subscriptions`, `paid-subscriptions-movement`, `subscriptions-overview`, `subscription-cancellation`), trials (`free-trials`, `active-trials`, `trials-movement`, `trial-cancellation`, `trial-to-paid`), and acquisition (`users-overview`, `user-to-trial`, `user-to-paid`). Plus back-compat aliases `user-to-trial-conversion` and `subscription-cancellation-rate`. The `chart_code` parameter on `GET /v4/analytics/charts/{chart_code}` (below) has the full machine-readable enum; use `GET /v4/analytics/charts/{chart_code}/meta` to discover available segmentation/filter codes for a given chart.
* **Realtime card** — `/v4/analytics/cards/realtime` returns today-so-far counters (trials, subscriptions, in-app purchases, tracked revenue) alongside the corresponding values at the same point yesterday. Surfaces in the dashboard header.
* **Cohorts** — Retention / conversion cohort matrices. Use `/v4/analytics/cohorts/meta` to discover available dimensions.
* **LTV** — Revenue LTV and trial-to-paid conversion LTV are separate endpoints.
* **Insights** — Pre-computed narrative insights surfaced on the dashboard home screen, including scalar KPIs (MRR, sales, proceeds, new users) plus AI-written observations.

## Available endpoints

| Method | Endpoint                              | Description                             | Status |
| ------ | ------------------------------------- | --------------------------------------- | ------ |
| GET    | `/analytics/cards/realtime`           | Today-so-far vs. yesterday counters     | New    |
| GET    | `/analytics/charts/{chart_code}`      | Get analytics chart data                | New    |
| GET    | `/analytics/charts/{chart_code}/meta` | Get analytics chart metadata            | New    |
| GET    | `/analytics/cohorts`                  | Get cohort analytics data               | New    |
| GET    | `/analytics/cohorts/meta`             | Get cohort analytics metadata           | New    |
| GET    | `/analytics/currencies`               | Get supported analytics currencies      | New    |
| GET    | `/analytics/insights`                 | Get analytics insights                  | New    |
| GET    | `/analytics/ltv`                      | Get LTV analytics data                  | New    |
| GET    | `/analytics/ltv/meta`                 | Get LTV analytics metadata              | New    |
| GET    | `/analytics/ltv/trial-conversion`     | Get LTV trial-conversion analytics data | New    |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Authentication
Source: https://documentation.qonversion.io/reference/v4/authentication

How to authenticate with the Qonversion REST API v4

The Qonversion REST API v4 uses Bearer token authentication.

## Secret Key

**All v4 public endpoints require a Secret Key.** Unlike v3, which mixed SDK-level access tokens with privileged server keys, v4 exposes only the server-to-server surface — so a single token type is used for every operation, from reads to privileged mutations (granting entitlements, managing products, experiment overrides, rotating credentials).

* Prefixed with `sk_`
* Found in **Project settings** in the [Qonversion dashboard](https://dash.qonversion.io)
* Passed as `Authorization: Bearer sk_…`

```bash theme={null}
curl --request GET \
  --url https://api.qonversion.io/v4/users/{user_id} \
  --header 'Authorization: Bearer sk_YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json'
```

<Warning>
  The Secret Key should only be stored on your server. **Never use the Secret Key in Android, iOS, or web apps.** Client apps authenticate through the Qonversion SDK, which uses a separate SDK-level token — not the public REST API v4.
</Warning>

## Sandbox vs production

Use a test-prefixed token to target the sandbox environment:

```
Authorization: Bearer test_sk_…  → sandbox
Authorization: Bearer sk_…       → production
```

The API behaves identically in both environments; data is isolated.

## Error codes

| Status | Error code             | When                                                              |
| ------ | ---------------------- | ----------------------------------------------------------------- |
| 401    | `control_unauthorized` | Missing or invalid Bearer token                                   |
| 403    | `control_forbidden`    | Valid token, insufficient permissions for the requested operation |

See [Handling Errors](/reference/v4/handling-api-errors) for the full error envelope.

## Coming from v3?

In v3 some endpoints accepted a non-secret **Project Key** (SDK-level access token) — for example, reading users or creating purchases. In v4 those endpoints live only on the server-to-server surface and require a **Secret Key**. Client SDKs continue to use their own access token and do not call the v4 public API directly.


# Automations
Source: https://documentation.qonversion.io/reference/v4/automations

Deprecated: the Automations product surface has been removed from Qonversion. The API remains available for existing integrations only. Event-driven automations that fire push notifications or show screens in response to user events.

<Warning>
  **Automations are deprecated.** The Automations product surface (including push notifications and screens triggered by user events) has been removed from the Qonversion dashboard. This API remains available for existing integrations only and should not be used for new development. No new Automations features are planned.
</Warning>

**Automations** bind a trigger (event type) to one or more actions (push, screen). They run for users of the project, optionally narrowed by platform and segment.

## Key concepts

* **Trigger** — one or more events that cause the automation to run (e.g. `Trial Started`, `In-App Purchase`, `Refund Declined`). Events are tracked by the Qonversion SDK and referenced here by their numeric `event_id` (see the **Events** tab in the dashboard).
* **Action** — the thing the automation does: send a `push` notification, or show a `screen`. Push and screen resources are created in the Qonversion dashboard; this API references them by `uid`.
* **Platform filter** — optional, one of `iOS`, `Android`, or omitted/null for all platforms.
* **Audience (`segments`)** — optional user segment uid (created via the **Segments** tab), or `null` to run for all users.
* **Status** — `active` (firing), `inactive`, or `paused`. Toggle via `PATCH /v4/automations/{id}/status`.

## `data` shape

The `data` field is an object with a fixed schema:

```json theme={null}
{
  "platform": "iOS",
  "initiators": [
    { "uid": "2", "type": "event" }
  ],
  "actions": {
    "push":   "nCRUE7SW",
    "screen": "qUY7JXgF"
  },
  "segments": null
}
```

* `platform` — `"iOS"`, `"Android"`, or `null`.
* `initiators` — array of one or more `{uid, type}` entries. `type` is always `"event"` today; `uid` is the dashboard event id.
* `actions` — object with optional `push` and/or `screen` uids. At least one action is required. The `event` key is reserved and currently ignored.
* `segments` — segment uid (string), or `null` for all users.

On read, the response additionally includes `"type"` (derived: `"event"` when any initiator is an event).

## Available endpoints

| Method | Endpoint                              | Description                                         |
| ------ | ------------------------------------- | --------------------------------------------------- |
| GET    | `/automations`                        | List automations (cursor-paginated)                 |
| POST   | `/automations`                        | Create an automation                                |
| GET    | `/automations/{automation_id}`        | Get an automation                                   |
| PUT    | `/automations/{automation_id}`        | Replace an automation (all mutable fields required) |
| DELETE | `/automations/{automation_id}`        | Delete an automation                                |
| PATCH  | `/automations/{automation_id}/status` | Toggle `active` / `inactive` / `paused`             |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).

## Notes & limits

* **Push and event creation are dashboard-only.** The v4 API writes automations against existing push/event uids; new pushes and SDK-sent event types are not created through this API.
* **255-char** limit on `name`, **1024-char** limit on `caption`.
* `caption` on read may contain pre-rendered HTML from the dashboard (e.g. `<span>` tags highlighting key phrases); it's a display-only field.
* Pagination uses the `limit` (1–100, default 20) and `starting_after` cursor parameters.


# Customers
Source: https://documentation.qonversion.io/reference/v4/customers

Aggregated customer records, properties, permissions, and metrics

A **Customer** is the v4 aggregated view of a user: their identifiers, properties, permissions, and lifetime metrics. Customer endpoints are intended for dashboards and server-side flows that need a consolidated picture — most client SDK flows should continue to use the User APIs.

## Key concepts

* **Customer ID** — The canonical ID for the customer (equivalent to the Qonversion User ID).
* **Permissions** — Access rights granted to the customer (granular alternative to entitlements).
* **Properties** — Same key–value model as user properties, but aggregated per customer.
* **Metrics** — Aggregated counters (total customers, active subscriptions, churn, etc.) exposed via `/v4/customers/metrics`.
* **GDPR delete** — `DELETE /v4/customers/{customer_id}` permanently removes all data for a customer.

## Available endpoints

| Method | Endpoint                                               | Description                      | Status |
| ------ | ------------------------------------------------------ | -------------------------------- | ------ |
| GET    | `/customers`                                           | List customers                   | New    |
| GET    | `/customers/metrics`                                   | Get customer metrics             | New    |
| DELETE | `/customers/{customer_id}`                             | Delete a customer (GDPR)         | New    |
| GET    | `/customers/{customer_id}`                             | Get a customer                   | New    |
| GET    | `/customers/{customer_id}/permissions`                 | List customer permissions        | New    |
| POST   | `/customers/{customer_id}/permissions`                 | Grant a permission to a customer | New    |
| DELETE | `/customers/{customer_id}/permissions/{permission_id}` | Revoke a customer permission     | New    |
| POST   | `/customers/{customer_id}/properties`                  | Set customer properties          | New    |

## Authentication

All v4 endpoints require a **Secret Key**. Deleting a customer (GDPR) and granting or revoking permissions are privileged operations in the manifest sense, but the token type is the same as for reads. See [Authentication](/reference/v4/authentication).


# Entitlements
Source: https://documentation.qonversion.io/reference/v4/entitlements

Create entitlement definitions and grant or revoke user access

**Entitlements** model premium access in your app. In v4 there are two layers: **entitlement definitions** (the list of entitlements available in the project, managed under `/v4/entitlements`) and **user entitlements** (grants attached to a specific user, under `/v4/users/{user_id}/entitlements`).

## Key concepts

* **Definition** — Project-level entitlement (e.g., `plus`, `premium`). Defines the ID, an optional description, and the products that grant it.
* **User entitlement** — A grant tied to a specific user, either earned via a purchase or granted manually.
* **Source** — `appstore`, `playstore`, `stripe`, `manual`, or `unknown`.
* **Expiration** — Subscriptions expire; non-recurring entitlements may be permanent.

## Available endpoints

| Method | Endpoint                                         | Description                                | Status                              |
| ------ | ------------------------------------------------ | ------------------------------------------ | ----------------------------------- |
| GET    | `/entitlements`                                  | List entitlement definitions               | New                                 |
| POST   | `/entitlements`                                  | Create an entitlement definition           | New                                 |
| DELETE | `/entitlements/{entitlement_id}`                 | Delete an entitlement definition           | New                                 |
| GET    | `/entitlements/{entitlement_id}`                 | Get an entitlement definition              | New                                 |
| PATCH  | `/entitlements/{entitlement_id}`                 | Update an entitlement definition (partial) | New                                 |
| GET    | `/users/{user_id}/entitlements`                  | List user entitlements                     | Updated — [v3](/reference/overview) |
| POST   | `/users/{user_id}/entitlements`                  | Grant an entitlement to a user             | Updated — [v3](/reference/overview) |
| DELETE | `/users/{user_id}/entitlements/{entitlement_id}` | Revoke a user entitlement                  | Updated — [v3](/reference/overview) |

## Authentication

All v4 endpoints require a **Secret Key**. Granting or revoking a user entitlement is a privileged operation in the manifest sense, but the token type is the same as for reads. See [Authentication](/reference/v4/authentication).


# Events
Source: https://documentation.qonversion.io/reference/v4/events

Browse the catalog of event types Qonversion tracks for use in custom dashboards, automations, and external integrations.

The **Events API** exposes the catalog of event types Qonversion tracks (e.g., `trial_started`, `subscription_renewed`). Use it to power custom dashboards, drive automations, or stream to external systems via [scheduled reports](/reference/v4/scheduled-reports) and [integrations](/reference/v4/integrations).

## Key concepts

* **Event type** — Stable string identifier for the class of event.

## Available endpoints

| Method | Endpoint  | Description | Status |
| ------ | --------- | ----------- | ------ |
| GET    | `/events` | List events | New    |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Experiments
Source: https://documentation.qonversion.io/reference/v4/experiments

Paywall and offering experiments, groups, and user assignment

**Experiments** enable A/B testing of paywalls, offerings, and remote configurations. Each experiment has one or more **groups** (variants), and users are attached to a specific group either automatically by audience rules or manually via the API.

## Key concepts

* **Status** — `draft`, `active`, `paused`, or `finished`. Drive transitions via `POST /v4/experiments/{experiment_id}/status`; finishing releases all assigned users.
* **Groups** — Variants within an experiment. Each group carries a payload (offering, screen, remote config value, etc.).
* **User attachment** — `POST /v4/experiments/{experiment_id}/users/{user_id}` pins a user to a group, overriding automatic evaluation; the assignment is never re-evaluated and persists until detached or the experiment finishes. Group membership is sticky: raising the traffic allocation never re-admits previously rejected users, and finishing the experiment releases everyone. Both attach and detach invalidate the SDK's in-memory config cache. See [Changing experiment traffic mid-flight](/docs/remote-config-targeting#changing-experiment-traffic-mid-flight).
* **Summary** — `/v4/experiments/summary` returns aggregated performance metrics. **Required:** `filter[experiment_uid][]` (1–50 UIDs) — discover via `GET /v4/experiments`, then iterate the summary in batches.

## Available endpoints

| Method | Endpoint                                         | Description                          | Status |
| ------ | ------------------------------------------------ | ------------------------------------ | ------ |
| GET    | `/experiments`                                   | List experiments                     | New    |
| POST   | `/experiments`                                   | Create an experiment                 | New    |
| GET    | `/experiments/summary`                           | Get experiments analytics summary    | New    |
| DELETE | `/experiments/{experiment_id}`                   | Delete an experiment                 | New    |
| GET    | `/experiments/{experiment_id}`                   | Get an experiment                    | New    |
| PATCH  | `/experiments/{experiment_id}`                   | Partially update an experiment       | New    |
| GET    | `/experiments/{experiment_id}/groups`            | List experiment groups               | New    |
| POST   | `/experiments/{experiment_id}/groups`            | Create an experiment group           | New    |
| DELETE | `/experiments/{experiment_id}/groups/{group_id}` | Delete an experiment group           | New    |
| PATCH  | `/experiments/{experiment_id}/groups/{group_id}` | Update an experiment group           | New    |
| POST   | `/experiments/{experiment_id}/status`            | Change experiment status             | New    |
| DELETE | `/experiments/{experiment_id}/users/{user_id}`   | Detach a user from an experiment     | New    |
| POST   | `/experiments/{experiment_id}/users/{user_id}`   | Attach a user to an experiment group | New    |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Exports
Source: https://documentation.qonversion.io/reference/v4/exports

Asynchronous data exports (customers, events, purchases)

The **Exports API** creates asynchronous jobs that produce CSV/JSON dumps of large resources — customers, events, purchases — filtered by date range and optional segments. Exports run in the background and notify via polling on the export status endpoint.

## Key concepts

* **Job lifecycle** — newly created jobs return as `New`, transition to `Processing` when a worker picks them up, then settle on `Done` (success) or `Failed` (error). The status string is reported by the upstream task system; treat unrecognised values as forward-compatibility fallbacks.
* **History** — `/v4/exports/history` lists previous export jobs with signed download URLs once completed.
* **Polling** — `GET /v4/exports/{export_id}` returns current status and download URL when ready.

## Available endpoints

| Method | Endpoint               | Description           | Status |
| ------ | ---------------------- | --------------------- | ------ |
| POST   | `/exports`             | Create export (async) | New    |
| GET    | `/exports/history`     | List past exports     | New    |
| GET    | `/exports/{export_id}` | Get export status     | New    |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Handling Errors
Source: https://documentation.qonversion.io/reference/v4/handling-api-errors

HTTP response codes and error format for the Qonversion REST API v4

The v4 API uses the same HTTP status codes and error envelope as v3.

## HTTP Response Codes

| Code | State                | Description                                                       |
| ---- | -------------------- | ----------------------------------------------------------------- |
| 200  | Success              | Everything worked as expected                                     |
| 201  | Created              | Operation led to creation of a resource                           |
| 204  | No Content           | Server fulfilled request, no content in response body             |
| 400  | Bad Request          | Request not accepted, often due to missing required parameter     |
| 401  | Unauthorized         | Invalid API key provided                                          |
| 403  | Forbidden            | Authorization by a Secret Key required                            |
| 404  | Not Found            | Requested resource does not exist                                 |
| 409  | Conflict             | Resource already exists or operation conflicts with current state |
| 422  | Unprocessable Entity | Cannot process request due to logical error                       |
| 429  | Too Many Requests    | Rate limit exceeded                                               |
| 5xx  | Server Errors        | Something went wrong on Qonversion's end (rare)                   |

## Error Response Format

All v4 errors follow a single envelope keyed under `error`. There is no envelope-level `meta` (or `_meta`) key — validation field errors live inside `error.details` as `{field, message}` pairs:

```json theme={null}
{
  "error": {
    "type": "request",
    "code": "invalid_data",
    "message": "Validation failed",
    "details": [
      { "field": "short_name", "message": "Value is too long" },
      { "field": "last_name", "message": "Required" }
    ]
  }
}
```

`error.details` is omitted entirely (rather than emitted as `null` or `[]`) when the failure is not field-scoped — for example, a 401 unauthorized or a 404 resource-not-found returns just `{type, code, message}`.

## Error Types

| Type       | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `request`  | Error in request validation (not enough data, invalid data, auth required)            |
| `resource` | Request is valid but the action could not be executed                                 |
| `logical`  | Client can execute action but there is an error in communicating with the application |
| `internal` | All request handling stages succeeded but an internal error occurred                  |

## Error Codes

### Request Errors

| Code                   | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `invalid_data`         | Validation failed. See `error.details` for the failing fields. |
| `invalid_request`      | Unrecognized request URL                                       |
| `control_unauthorized` | Authorization required                                         |
| `control_forbidden`    | Authenticated but not allowed (wrong key type or scope)        |
| `not_implemented`      | Functionality at the requested address is not implemented      |
| `rate_limited`         | Too many requests — back off and retry                         |

### Resource Errors

| Code             | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `not_found`      | Requested resource not found                          |
| `already_exists` | Requested resource already exists                     |
| `conflict`       | Resource state conflicts with the requested operation |

### Logical Errors

| Code                 | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `purchase_fraud`     | Could not validate purchase with store, potential fraud |
| `relation_not_found` | Nested objects could not be found or associated         |

### Internal Errors

| Code            | Description                          |
| --------------- | ------------------------------------ |
| `storage_error` | Data was not saved                   |
| `network_error` | Internal services interaction failed |
| `unknown_error` | Unknown reason                       |


# Identities
Source: https://documentation.qonversion.io/reference/v4/identities

Link Qonversion users to your own authentication system

An **Identity** binds a Qonversion User ID to your own external user ID (e.g., your auth system's primary key). This enables consistent user tracking across devices and platforms. Identities are the preferred way to reconcile anonymous SDK users with authenticated users after login.

## Key concepts

* **Identity ID** — The external ID you control (e.g., `user_42`). Up to 255 characters, alphanumeric + `.`, `_`, `-`.
* **Qonversion User ID** — The `QON_…` ID the identity is attached to.
* **Append-only** — Identities cannot be re-bound via this API. POSTing the same `identity_id` twice (even with a different `user_id`) returns `409 Identity already exists`.
* **Create shape** — v3 used `POST /identities/{identity_id}`; v4 replaces this with `POST /identities` where the identity ID is sent in the body for cleaner REST semantics.

## Available endpoints

| Method | Endpoint                    | Description                    | Status                              |
| ------ | --------------------------- | ------------------------------ | ----------------------------------- |
| POST   | `/identities`               | Create an identity link        | New                                 |
| GET    | `/identities/{identity_id}` | Get an identity by external ID | Updated — [v3](/reference/overview) |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Integrations
Source: https://documentation.qonversion.io/reference/v4/integrations

Configure third-party integrations with marketing, analytics, attribution, and messaging platforms through the v4 API.

**Integrations** connect Qonversion to external marketing, analytics, attribution, and messaging platforms (Amplitude, Mixpanel, AppsFlyer, Adjust, Branch, Facebook, webhooks, etc.). An integration in v4 is the *pipeline record* — created with a display title and a target platform, then activated or paused. Per-provider credentials (API keys, webhook secrets) are configured out-of-band after creation; v4 does not expose credential fields.

## Key concepts

* **Catalog** — `GET /v4/integrations/meta` returns the list of supported provider slugs grouped by category, with the store platforms each slug supports.
* **Status** — Integrations are paused (`active=0`) or active (`active=1`). `active=2` (error) is set by the delivery worker when upstream rejects events — callers cannot set it.
* **Lifecycle** — Delete is soft: the record is flagged and stops forwarding events. The ID cannot be reused.

## Supported integration slugs

Pass one of the following values as `integration` when calling `POST /v4/integrations`. The canonical list is whatever `/v4/integrations/meta` returns; this table is a point-in-time snapshot.

| Category              | Slugs                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| Analytics & marketing | `amplitude`, `appmetrica`, `facebook`, `firebase`, `mixpanel`, `posthog`, `segment`                      |
| Attribution           | `searchads`, `adjust`, `appsflyer`, `branch`, `kochava`, `singular`, `split_metrics`, `asapty`, `tenjin` |
| Server                | `amazon_s3`, `google_cloud_storage`, `slack`, `webhooks`                                                 |
| Email & push          | `braze`, `clevertap`, `mailchimp`, `onesignal`, `pushwoosh`                                              |

Not every slug is available for every `target_platform`. `/v4/integrations/meta` reports `allowedStores` per slug.

## `target_platform` values

The target platform is **case-sensitive**:

| Value     | Store           |
| --------- | --------------- |
| `iOS`     | Apple App Store |
| `Android` | Google Play     |
| `Stripe`  | Stripe          |

## `active` status

| Value | Meaning                                                                          | Who sets it                                                          |
| ----- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `0`   | Paused / draft — no events forwarded.                                            | Callers (create default, `POST /status`)                             |
| `1`   | Active — events forwarded.                                                       | Callers (`POST /status`)                                             |
| `2`   | Error — delivery worker suspended the pipeline after repeated upstream failures. | Qonversion worker. Inspect `last_error_message` and `last_error_at`. |

To recover from `active=2`, fix the upstream credentials and `POST /status` with `{"status": 1}`.

## Available endpoints

| Method | Endpoint                                   | Description                                                      |
| ------ | ------------------------------------------ | ---------------------------------------------------------------- |
| GET    | `/v4/integrations`                         | List integrations (no pagination — returns the full project set) |
| POST   | `/v4/integrations`                         | Create integration                                               |
| GET    | `/v4/integrations/meta`                    | Get supported-provider catalog                                   |
| POST   | `/v4/integrations/{integration_id}/status` | Pause (0) or activate (1) an integration                         |
| DELETE | `/v4/integrations/{integration_id}`        | Delete integration (soft; ID cannot be reused)                   |

## Example: create an Amplitude pipeline for iOS

```bash theme={null}
curl -X POST https://api.qonversion.io/v4/integrations \
  -H "Authorization: Bearer $QONVERSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Amplitude — Production iOS",
    "integration": "amplitude",
    "target_platform": "iOS"
  }'
```

Response (`201 Created`):

```json theme={null}
{
  "object": "integration",
  "id": "gNl6hyM6",
  "url": "/v4/integrations/gNl6hyM6",
  "title": "Amplitude — Production iOS",
  "integration": "Amplitude",
  "target_platform": "iOS",
  "active": 0,
  "created_at": "2026-02-26T16:03:09Z",
  "updated_at": "2026-02-26T16:03:09Z",
  "last_delivery_at": null,
  "last_error_at": null,
  "last_error_message": null,
  "delivery_error_count": 0
}
```

The `integration` field in responses carries the **display title** (e.g. `Amplitude`), not the lowercase slug you sent on create. Treat slugs as write-only identifiers; use `id` for references in other requests.

## Example: activate then pause

```bash theme={null}
# Activate
curl -X POST "https://api.qonversion.io/v4/integrations/gNl6hyM6/status" \
  -H "Authorization: Bearer $QONVERSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status": 1}'

# Pause
curl -X POST "https://api.qonversion.io/v4/integrations/gNl6hyM6/status" \
  -H "Authorization: Bearer $QONVERSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status": 0}'
```

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Offerings
Source: https://documentation.qonversion.io/reference/v4/offerings

Legacy: Offerings are superseded by Remote Configs. Bundles of products shown to users in paywalls; kept available for existing integrations. Migrate new work to Remote Configs.

<Warning>
  **Offerings are legacy.** [Remote Configs](/docs/remote-config) have replaced Offerings for all new integrations, and creating new offerings is being phased out. Existing offerings and the `offerings()` SDK method keep working, so already-shipped paywalls are unaffected. For any new work, use Remote Configs instead — see [Migrate Offerings to Remote Configs](/docs/migrate-offerings-to-remote-configs).
</Warning>

An **Offering** is a named bundle of products that the SDK consumes to render a paywall or purchase flow. Offerings decouple the products a user sees from the product IDs in your app code — you can change the contents of an offering without shipping a new build. At most one offering per project is marked as the **main** offering and is returned to the SDK by default when no specific id is requested.

## Key concepts

* **Offering ID** — Stable identifier you choose (e.g., `onboarding`, `winback`). Used in the API path and in related resources (experiments, scheduled reports). Up to 64 characters; allowed characters are `a–z`, `A–Z`, `0–9`, `.`, `_`, `-`, `:`, and spaces. Immutable after create.
* **Products** — An ordered list of product UIDs attached to the offering. The SDK renders them in the order you define. Each UID must already exist in the same project; product UIDs are up to 255 characters from the same charset as offering ids.
* **Main offering** — At most one offering per project carries `tag: 1`. Use `POST /v4/offerings/{offering_id}/set-main` to switch the main — it atomically clears the previous main inside a single transaction. `tag=1` on `POST /offerings` and `PATCH /offerings/{id}` is rejected with `400` (typed code `cannot_set_main_directly`). To make an offering the project's main, create or patch it without `tag` and call `POST /offerings/{id}/set-main` afterward — that endpoint flips the main flag atomically. Patching the project's current main offering with `tag: 0` (or any non-main value) is rejected with `422` (typed code `cannot_demote_main`). To switch which offering is main, call `POST /offerings/{new-main-id}/set-main` — the previous main is cleared in the same transaction.
* **Tag** — On read: `1` = main offering, `0` = regular offering previously demoted from main, `null` = regular offering that has never been tagged. Treat `0` and `null` as equivalent on read. Tag is read-only via `PATCH`; use `set-main` to promote and `set-main` on a different offering to implicitly demote the current main. On `POST` only `0` and `null` are accepted (and `tag=1` is rejected as above). The very first offering created in an empty project is auto-promoted to `tag: 1` even if `tag` is omitted in the request.
* **Experiment-variant offerings** — Offerings owned by the experiments service are excluded from `GET /offerings` and return `404` from `GET /offerings/{offering_id}`. `PATCH`, `DELETE`, and `set-main` on an experiment-variant id return `422` with typed codes `cannot_patch_experiment_variant`, `cannot_delete_experiment_variant`, and `cannot_setmain_experiment_variant` respectively.

## Offering object

| Field         | Type            | Description                                |
| ------------- | --------------- | ------------------------------------------ |
| `object`      | string          | Always `offering`.                         |
| `id`          | string          | Offering identifier.                       |
| `url`         | string          | Canonical API path (`/v4/offerings/{id}`). |
| `tag`         | integer \| null | `1` = main, `0` or `null` = regular.       |
| `product_ids` | string\[]       | Product UIDs in display order.             |
| `created_at`  | string          | ISO 8601 UTC creation timestamp.           |
| `updated_at`  | string          | ISO 8601 UTC last-update timestamp.        |

## Available endpoints

| Method | Endpoint                            | Description                                       | Status |
| ------ | ----------------------------------- | ------------------------------------------------- | ------ |
| GET    | `/offerings`                        | List offerings                                    | New    |
| POST   | `/offerings`                        | Create an offering                                | New    |
| GET    | `/offerings/{offering_id}`          | Get an offering                                   | New    |
| PATCH  | `/offerings/{offering_id}`          | Update an offering (partial)                      | New    |
| DELETE | `/offerings/{offering_id}`          | Delete an offering                                | New    |
| POST   | `/offerings/{offering_id}/set-main` | Mark this offering as the project's main offering | New    |

`PATCH` replaces `product_ids` with the supplied list — pass `[]` to detach all products, or omit the field to leave the list unchanged.

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).

## Errors

The Offerings API follows the standard error envelope and codes documented on [Handling Errors](/reference/v4/handling-api-errors).

| Code                                | HTTP | Description                                                                                                                                                                  |
| ----------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `not_found`                         | 404  | Offering does not exist in this project, or the id belongs to an experiment-variant offering filtered out by `GET`.                                                          |
| `offering_already_exists`           | 409  | `POST /offerings` was called with an `id` that already exists in this project.                                                                                               |
| `product_not_in_project`            | 400  | `product_ids` references a product UID that is not registered in the project.                                                                                                |
| `cannot_set_main_directly`          | 400  | `tag: 1` was sent on `POST /offerings` or `PATCH /offerings/{id}`. Call `POST /offerings/{id}/set-main` instead.                                                             |
| `cannot_demote_main`                | 422  | `PATCH /offerings/{id}` tried to set `tag: 0` (or any non-main value) on the project's current main offering. Promote a different offering via `set-main` to switch instead. |
| `cannot_patch_experiment_variant`   | 422  | `PATCH /offerings/{id}` was called against an offering owned by the experiments service.                                                                                     |
| `cannot_delete_experiment_variant`  | 422  | `DELETE /offerings/{id}` was called against an offering owned by the experiments service.                                                                                    |
| `cannot_setmain_experiment_variant` | 422  | `POST /offerings/{id}/set-main` was called against an offering owned by the experiments service.                                                                             |


# Overview
Source: https://documentation.qonversion.io/reference/v4/overview

The Qonversion REST API v4 consolidates customer, analytics, experiment, segment, and integration management with an agent-first design.

The Qonversion REST API v4 is the current generation of our public HTTP API. It consolidates everything that was previously scattered across v3 endpoints and adds first-class management of customers, analytics, experiments, segments, screens, integrations, automations, scheduled reports, exports, and project settings.

<Note>
  v4 is available alongside v3. Existing integrations on v3 keep working; migrate resource by resource when convenient. Each endpoint in the guides below is tagged **New** or **Updated** with a link back to its v3 counterpart.
</Note>

## Designed for agents and MCP

v4 was built with AI agents and the [Model Context Protocol](https://modelcontextprotocol.io) in mind. Every public resource in v4 is also exposed through the official **[Qonversion MCP server](/docs/mcp-server)**, so the same API surface is callable directly from Claude, ChatGPT, Cursor, and any other MCP-compatible client — without a custom wrapper.

Concretely, v4 follows a set of rules that make it safe and predictable for an agent to use:

* **Stable, verb-based operation IDs** (e.g., `v4CreateScreen`, `v4ListExperiments`) — MCP tools map 1-to-1 to operations.
* **Consistent resource-oriented URLs** — `/v4/{resource}` for collections, `/v4/{resource}/{id}` for items, sub-resources nested only one level deep.
* **Paginated lists** with uniform `limit` / `starting_after` cursors, so agents can iterate deterministically.
* **Idempotent mutations** where feasible (PUT, PATCH, and DELETE are safe to retry).
* **One token type over HTTP** — v4 public endpoints all authenticate with the project Secret Key; the MCP server uses OAuth 2.1 with per-tool scopes instead, so AI clients never handle the Secret Key directly.
* **Machine-readable errors** — every error includes `type`, `code`, and field-level details so an agent can self-correct without parsing prose.

If you're building an agentic workflow on top of Qonversion, prefer v4.

## Base URL

All v4 API requests should be made to:

```
https://api.qonversion.io/v4
```

## API Sections

| Section                                                      | Description                                                                                                                             |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| [Users](/reference/v4/users)                                 | Retrieve Qonversion users, manage user-level purchases, properties, and entitlements                                                    |
| [User Properties](/reference/v4/user-properties)             | Manage user-level attributes for segmentation and analytics                                                                             |
| [Identities](/reference/v4/identities)                       | Link Qonversion users to your own auth system IDs                                                                                       |
| [Entitlements](/reference/v4/entitlements)                   | Create entitlement definitions and grant / revoke access                                                                                |
| [Purchases](/reference/v4/purchases)                         | Inspect a user's purchase history                                                                                                       |
| [Products](/reference/v4/products)                           | Manage products configured in the Qonversion dashboard                                                                                  |
| [Offerings](/reference/v4/offerings) *(legacy)*              | Bundles of products shown to users in paywalls. Legacy — use [Remote Configs](/reference/v4/remote-configurations) instead              |
| [Remote Configurations](/reference/v4/remote-configurations) | Server-driven configuration payloads delivered to the SDK                                                                               |
| [Customers](/reference/v4/customers)                         | Aggregated customer data, properties, permissions, and metrics                                                                          |
| [Segments](/reference/v4/segments)                           | Dynamic and system segments of users                                                                                                    |
| [Experiments](/reference/v4/experiments)                     | Paywall / offering experiments, groups, and user assignment                                                                             |
| [Screens](/reference/v4/screens) *(deprecated)*              | No-code paywall screens — CRUD, publish, duplicate, analytics. Deprecated — product surface removed, API for existing integrations only |
| [Analytics](/reference/v4/analytics)                         | Charts, cards, cohorts, LTV, and insights                                                                                               |
| [Exports](/reference/v4/exports)                             | Asynchronous data exports (customers, events, purchases)                                                                                |
| [Events](/reference/v4/events)                               | Event catalog                                                                                                                           |
| [Scheduled Reports](/reference/v4/scheduled-reports)         | Recurring reports sent to external destinations                                                                                         |
| [Integrations](/reference/v4/integrations)                   | Third-party integrations configuration                                                                                                  |
| [Automations](/reference/v4/automations) *(deprecated)*      | Event-driven automations. Deprecated — product surface removed, API for existing integrations only                                      |
| [Project Settings](/reference/v4/project-settings)           | Project-level configuration, secret, and store credentials                                                                              |

## Request Format

All requests must include:

* `Authorization` header with a Bearer token (see [Authentication](/reference/v4/authentication))
* `Content-Type: application/json` for `POST`, `PUT`, `PATCH`, `DELETE` requests

## Response Format

All responses are JSON-encoded. List endpoints return paginated results. Error responses follow a consistent [error format](/reference/v4/handling-api-errors).


# Products
Source: https://documentation.qonversion.io/reference/v4/products

Manage products configured in the Qonversion dashboard

A **Product** in Qonversion maps your store SKU (App Store product ID, Play Store product ID, or Stripe price ID) to a stable Qonversion product identifier. Products are referenced by entitlements, offerings, experiments, and analytics.

## Key concepts

* **Product ID** — Stable identifier you choose (e.g., `premium_monthly`). Used in the API path and in related resources (entitlements, offerings, experiments). Up to 255 characters, restricted to alphanumerics, hyphens, underscores, and dots.
* **Type** — One of `subscription_with_promo`, `subscription`, `consumable`, or `lifetime`. May be `null` for legacy products that pre-date typed products. Labels match the Qonversion dashboard.
* **Duration** — ISO 8601 subscription period: `P1W`, `P1M`, `P3M`, `P6M`, or `P1Y`. Allowed only for `subscription_with_promo` and `subscription`; `null` for `consumable` and `lifetime`.
* **Path consolidation** — v3 split product operations between `/products/{id}` (GET) and `/products/{uid}` (PUT/PATCH/DELETE); v4 uses a single path `/products/{product_id}` for all operations.

## Product object

| Field                 | Type           | Description                                                                                            |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
| `object`              | string         | Always `product`.                                                                                      |
| `id`                  | string         | Qonversion product identifier.                                                                         |
| `url`                 | string         | Canonical API path (`/v4/products/{id}`).                                                              |
| `type`                | string \| null | Product type: `subscription_with_promo`, `subscription`, `consumable`, `lifetime`.                     |
| `duration`            | string \| null | ISO 8601 subscription period: `P1W`, `P1M`, `P3M`, `P6M`, `P1Y`. Null for `consumable` and `lifetime`. |
| `apple_product_id`    | string \| null | App Store Connect product identifier.                                                                  |
| `google_product_id`   | string \| null | Google Play Console product identifier.                                                                |
| `google_base_plan_id` | string \| null | Google Play base plan identifier.                                                                      |
| `stripe_product_id`   | string \| null | Stripe product identifier.                                                                             |
| `created_at`          | string         | ISO 8601 UTC creation timestamp.                                                                       |
| `updated_at`          | string         | ISO 8601 UTC last-update timestamp.                                                                    |

## Available endpoints

| Method | Endpoint                 | Description                | Status                              |
| ------ | ------------------------ | -------------------------- | ----------------------------------- |
| GET    | `/products`              | List products              | Updated — [v3](/reference/overview) |
| POST   | `/products`              | Create a product           | Updated — [v3](/reference/overview) |
| GET    | `/products/{product_id}` | Get a product              | Updated — [v3](/reference/overview) |
| PATCH  | `/products/{product_id}` | Update a product (partial) | Updated — [v3](/reference/overview) |
| DELETE | `/products/{product_id}` | Delete a product           | Updated — [v3](/reference/overview) |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Project Settings
Source: https://documentation.qonversion.io/reference/v4/project-settings

Project-level configuration, secret, and store credentials

The **Project Settings API** manages the project's top-level configuration: general settings, the project Secret Key, and per-platform store credentials (App Store shared secret / Connect API keys, Play Store service account key).

## Key concepts

* **General settings** — Project display name and optional proxy URLs (`proxy_url` for SDK traffic, `rtdn_proxy_url` for Play Store RTDN callbacks).
* **Secret rotation** — `POST /v4/project-settings/regenerate-secret` rotates the `sk_…` key. The old key is revoked; clients may see a short grace period (seconds) while internal caches expire.
* **Store config** — `GET` / `POST /v4/project-settings/stores/{platform}` where `platform` is `apple` or `google`. Stripe store config is not exposed via this API. Apple requires the App Store Connect API triplet (`connect_key_identifier` + `connect_private_key` + `connect_issuer_id`) to be sent together; same for the In-App Purchase API triplet (`iap_key_identifier` + `iap_private_key` + `iap_issuer_id`). Submitting only 1–2 of a triplet returns 422.

## Available endpoints

| Method | Endpoint                              | Description                                      | Status |
| ------ | ------------------------------------- | ------------------------------------------------ | ------ |
| GET    | `/project-settings`                   | Get project settings                             | New    |
| PATCH  | `/project-settings`                   | Update project settings                          | New    |
| POST   | `/project-settings/regenerate-secret` | Regenerate project secret key                    | New    |
| GET    | `/project-settings/stores/{platform}` | Get store configuration (`apple` or `google`)    | New    |
| POST   | `/project-settings/stores/{platform}` | Update store configuration (`apple` or `google`) | New    |

## Sensitive fields

Secrets (Apple shared secret, Apple Connect/IAP private keys, Google service account key) are **never returned** in `GET` responses. Instead the response includes boolean flags — `has_shared_secret`, `has_connect_private_key`, `has_iap_private_key`, `has_service_account_key` — that tell you whether the value is set.

On `POST` (update), omitting a secret field preserves the existing value. To rotate a secret, send the new value explicitly.

## Authentication

All v4 endpoints require a **Secret Key**. Rotating the Secret Key and updating store credentials are privileged operations in the manifest sense, but the token type is the same as for reads. See [Authentication](/reference/v4/authentication).


# Purchases
Source: https://documentation.qonversion.io/reference/v4/purchases

Retrieve a user transaction history from the App Store, Play Store, and Stripe for subscriptions and one-time purchases.

**Purchases** represent transactions recorded for a user — subscriptions, non-consumables, and consumables — originating from App Store, Play Store, or Stripe. In v4 the user-scoped purchases endpoint is read-only; purchases are created by Qonversion SDKs from store receipts or by the dedicated server-to-server import flow for Stripe.

## Key concepts

* **Platform** — `app_store`, `play_store`, or `stripe`. Determines the shape of `store_data`.
* **Transaction** — Each row represents one store transaction, ordered by `purchased_at` (newest first).
* **Product reference** — Purchases reference the Qonversion product by ID/UID. For Play Store subscriptions with a base plan, `product_id` is `{product_id}:{base_plan_id}`.
* **Expiry** — `expires_at` is `null` for one-time purchases and consumables.

## Available endpoints

| Method | Endpoint                     | Description               | Status |
| ------ | ---------------------------- | ------------------------- | ------ |
| GET    | `/users/{user_id}/purchases` | List purchases for a user | New    |

## Filtering

* `filter[platform]` — Repeat the query parameter to match multiple platforms with OR logic. Up to 3 values accepted. Example: `?filter[platform]=app_store&filter[platform]=stripe`.

## Pagination

Cursor-based. Pass the `id` of the last purchase from the previous page as `starting_after` to fetch the next page. `next_cursor` is non-null only when `has_more` is `true`.

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Remote Configurations
Source: https://documentation.qonversion.io/reference/v4/remote-configurations

Server-driven configuration payloads delivered to the SDK

A **Remote Configuration** is a named payload that the Qonversion SDK fetches at runtime. Use it to feature-flag experiments, change onboarding copy, tune paywall defaults, or deliver any server-controlled JSON to your app without a new release. Configurations can be narrowed with targeting rules, attached to experiment groups, or pinned to specific users.

## Key concepts

* **Config ID** — Stable identifier (UUID) for the configuration, used in the API path.
* **Context key** — Optional key the SDK uses to look up this configuration.
* **Status** — `draft`, `active`, or `archived`. Only `active` configurations are served to the SDK. Archiving is terminal; an archived configuration can only be deleted. Change it via `PATCH /remote-configurations/{config_id}/status`.
* **Payload values** — The actual JSON object delivered to the SDK, e.g. `{"button_color": "#FF0000"}`. Read and replaced through the dedicated `payload` endpoint, and also returned read-only inline on a single-configuration GET.
* **Payload mapping** — The key → type *schema* that tells the SDK how to interpret each payload key, e.g. `{"button_color": "Color"}`. Types are `String`, `Number`, `Bool`, `Json`, `Color`, `Products`, `Screens`. Managed through the `payload-mapping` endpoint. The mapping describes the shape of the payload; it is **not** the values themselves.
* **Targeting** — `segment_percent` (0–100) rolls the configuration out to a fraction of the audience, and `segmentation_conditions` narrows it with attribute rules. Both are set on create/update and returned on read. The rollout is deterministic per user: raising the percent only adds users, lowering it only removes users from the top buckets on their next request. Automatic assignments are re-evaluated after targeting edits (rolling out project by project); manual pins are never re-evaluated. See [How targeting and assignment works](/docs/remote-config-targeting).
* **User attachment** — `POST /remote-configurations/{config_id}/users/{user_id}` pins a specific user to this configuration, overriding targeting rules; the pin is never re-evaluated and survives config edits until `DELETE`, archive, or delete. Both attach and detach invalidate the SDK's in-memory config cache.
* **Experiments** — Remote configurations can be delivered as an experiment group payload.

<Note>
  **Payload values vs. payload mapping** are two sibling concepts. The **values** (`payload`) are the JSON delivered to the SDK; the **mapping** (`payload-mapping`) is the key → type schema describing how to read that JSON. They are edited through separate endpoints.
</Note>

## Available endpoints

| Method | Endpoint                                             | Description                                        | Status |
| ------ | ---------------------------------------------------- | -------------------------------------------------- | ------ |
| GET    | `/remote-configurations`                             | List remote configurations                         | New    |
| POST   | `/remote-configurations`                             | Create a remote configuration                      | New    |
| GET    | `/remote-configurations/{config_id}`                 | Get a remote configuration (with inline `payload`) | New    |
| PUT    | `/remote-configurations/{config_id}`                 | Replace a remote configuration                     | New    |
| DELETE | `/remote-configurations/{config_id}`                 | Delete a remote configuration                      | New    |
| PATCH  | `/remote-configurations/{config_id}/status`          | Change status (`draft`, `active`, `archived`)      | New    |
| GET    | `/remote-configurations/{config_id}/payload`         | Get the payload values                             | New    |
| PUT    | `/remote-configurations/{config_id}/payload`         | Replace the payload values                         | New    |
| GET    | `/remote-configurations/{config_id}/payload-mapping` | Get the payload mapping                            | New    |
| POST   | `/remote-configurations/{config_id}/payload-mapping` | Set the payload mapping                            | New    |
| POST   | `/remote-configurations/{config_id}/users/{user_id}` | Attach a user to this configuration                | New    |
| DELETE | `/remote-configurations/{config_id}/users/{user_id}` | Detach a user                                      | New    |

`POST` and `PUT` on a configuration accept the optional targeting fields `segment_percent` and `segmentation_conditions`, and both are returned on read. Only a single-configuration `GET` returns the read-only inline `payload` values (`{}` when unset) — list items and the create, update, and status responses omit them.

<Note>
  Both payload endpoints (`payload` and `payload-mapping`) are **full replace**: the object you send becomes the complete stored value. To change one key, read the current object, modify it, and send the whole object back. An empty object `{}` clears it. Payload value requests are limited to 64 KiB.
</Note>

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Scheduled Reports
Source: https://documentation.qonversion.io/reference/v4/scheduled-reports

Recurring analytics reports sent to external destinations

**Scheduled reports** deliver analytics snapshots on a recurring schedule — once per day, at a fixed UTC time — to configured destinations (Slack, webhooks, etc.). Each report is parameterised by the time window it covers (`included_range_days`) and the destinations it fans out to.

Destinations are not configured in this API: they are **integration destinations** created via the [Integrations API](/reference/v4/integrations). Use `GET /v4/scheduled-reports/destinations` to discover what's available for the project, then reference the destination by `{type, id}` when creating or updating a report.

## Key concepts

* **Send time** — `send_at` is a UTC time-of-day in `HH:MM` format, aligned to 30-minute slots (`"00:00"` … `"23:30"`). The daily job runs within a few minutes of this time.
* **Coverage window** — `included_range_days` is the number of days of data bundled into each delivery. Only three values are supported: `1`, `3`, `7`.
* **Status** — Reports are `"draft"` (paused, no deliveries) or `"active"` (scheduled).
* **Environment** — Each report targets a single environment: `"sandbox"` or `"production"`.
* **Send test** — `POST /v4/scheduled-reports/{report_id}/send-test` triggers an immediate one-off delivery. Rate-limited to one call per minute per report (returns `429` if exceeded).

## `send_at` values

Must be in UTC `HH:MM`, aligned to 30-minute slots, `"00:00"` to `"23:30"`:

```
"00:00", "00:30", "01:00", ..., "09:00", "09:30", ..., "23:00", "23:30"
```

`"23:45"` is invalid (not aligned). `"12:15"` is invalid (not aligned). `"24:00"` is invalid (out of range).

## `included_range_days` values

Only three values are accepted:

| Value | Description                                             |
| ----- | ------------------------------------------------------- |
| `1`   | Prior day (most recent UTC day closed before `send_at`) |
| `3`   | Prior 3 days                                            |
| `7`   | Prior 7 days                                            |

## `status` values

| Value      | Meaning                                           |
| ---------- | ------------------------------------------------- |
| `"draft"`  | Paused — no deliveries are scheduled.             |
| `"active"` | Active — enqueued for delivery at each `send_at`. |

## `environment` values

| Value          | Meaning                                    |
| -------------- | ------------------------------------------ |
| `"sandbox"`    | Report covers sandbox/testing events only. |
| `"production"` | Report covers live production events.      |

## Destinations

A destination is a `{type, id}` pair. `type` is a namespaced kind; `id` is the destination's opaque identifier. The only type currently exposed is `target_integration`, which points at an integration destination created via the [Integrations API](/reference/v4/integrations) (typically a webhook, Slack channel, or email endpoint).

Call `GET /v4/scheduled-reports/destinations` to enumerate all valid destinations for a project before creating or updating a report.

## Available endpoints

| Method | Endpoint                                      | Description                                             |
| ------ | --------------------------------------------- | ------------------------------------------------------- |
| GET    | `/v4/scheduled-reports`                       | List scheduled reports (paginated via `limit`/`offset`) |
| POST   | `/v4/scheduled-reports`                       | Create scheduled report                                 |
| GET    | `/v4/scheduled-reports/destinations`          | List available destinations                             |
| GET    | `/v4/scheduled-reports/{report_id}`           | Get scheduled report                                    |
| PUT    | `/v4/scheduled-reports/{report_id}`           | Partially update scheduled report                       |
| DELETE | `/v4/scheduled-reports/{report_id}`           | Delete scheduled report                                 |
| POST   | `/v4/scheduled-reports/{report_id}/send-test` | Trigger a one-off test delivery (202; rate-limited)     |

## Example: create an active daily report at 09:00 UTC

```bash theme={null}
curl -X POST https://api.qonversion.io/v4/scheduled-reports \
  -H "Authorization: Bearer $QONVERSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "report_name": "Daily Revenue",
    "send_at": "09:00",
    "included_range_days": 1,
    "status": "active",
    "environment": "production",
    "destinations": [
      { "type": "target_integration", "id": "int-wh-01" }
    ]
  }'
```

Response (`201 Created`):

```json theme={null}
{
  "object": "scheduled_report",
  "id": "wbRlfw1x",
  "url": "/v4/scheduled-reports/wbRlfw1x",
  "report_name": "Daily Revenue",
  "send_at": "09:00",
  "included_range_days": 1,
  "status": "active",
  "environment": "production",
  "runs": 0,
  "destinations": [
    {
      "type": "target_integration",
      "id": "int-wh-01",
      "label": "Webhooks: Release alerts"
    }
  ],
  "created_at": "2026-04-23T11:44:36Z",
  "updated_at": "2026-04-23T11:44:36Z"
}
```

## Example: partial update (pause a report)

`PUT` accepts a partial body — omit any field to keep it unchanged. To pause a report, send only the new `status`:

```bash theme={null}
curl -X PUT "https://api.qonversion.io/v4/scheduled-reports/wbRlfw1x" \
  -H "Authorization: Bearer $QONVERSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status": "draft"}'
```

## Example: send a one-off test

Useful when verifying destination credentials or report content:

```bash theme={null}
curl -X POST "https://api.qonversion.io/v4/scheduled-reports/wbRlfw1x/send-test" \
  -H "Authorization: Bearer $QONVERSION_SECRET"
```

Returns `202 Accepted` immediately; the delivery runs asynchronously.

The send-test endpoint is rate-limited to one call per minute per report. Repeated calls within 60 seconds return `429 Too Many Requests` with a `Retry-After: 60` header.

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Screens
Source: https://documentation.qonversion.io/reference/v4/screens

Deprecated: the Screens product surface has been removed from Qonversion. The API remains available for existing integrations only. No-code paywall screens — CRUD, publish, duplicate, and analytics.

<Warning>
  **Screens are deprecated.** The Screens product surface has been removed from the Qonversion dashboard. This API remains available for existing integrations only and should not be used for new development. No new Screens features are planned.
</Warning>

**Screens** are the no-code paywalls and onboarding flows built in the Qonversion dashboard or programmatically via the API. Each screen has a draft and a published version; users see the published version in the app.

## Key concepts

* **Draft vs. published** — Edits create a new draft; `POST /v4/screens/{screen_id}/publish` promotes it.
* **Context key** — Screens are shown in the SDK via `NoCodes.showScreen(contextKey)`.
* **Copy** — `POST /v4/screens/{screen_id}/copy` duplicates a screen, useful when forking variants.
* **Analytics** — Per-screen and overview analytics are available under `/v4/screens/analytics/…`.
* **Summary vs. full payload** — `GET /v4/screens/{screen_id}` returns the full `V4Screen` with render-time fields by default. Pass `?render=false` to get the lean `V4ScreenSummary` (same shape as list rows) when you only need metadata and want to skip the render payload (`configs`, `content`, `prod_key`, `sandbox_key`, `background`, `default_lang`, `used`).

## Available endpoints

| Method | Endpoint                         | Description                    | Status |
| ------ | -------------------------------- | ------------------------------ | ------ |
| GET    | `/screens`                       | List screens                   | New    |
| POST   | `/screens`                       | Create a screen                | New    |
| GET    | `/screens/analytics/overview`    | Get screens analytics overview | New    |
| DELETE | `/screens/{screen_id}`           | Delete a screen                | New    |
| GET    | `/screens/{screen_id}`           | Get a screen                   | New    |
| PUT    | `/screens/{screen_id}`           | Update a screen                | New    |
| GET    | `/screens/{screen_id}/analytics` | Get per-screen analytics       | New    |
| POST   | `/screens/{screen_id}/copy`      | Duplicate a screen             | New    |
| POST   | `/screens/{screen_id}/publish`   | Publish a screen               | New    |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).

## Programmatic creation, dashboard editing

`POST /v4/screens` only takes a `name`. It creates an empty draft — the layout, media, components, and localisations are then built in the Qonversion dashboard's no-code editor, which fills in `configs`, `content`, `background`, `default_lang`, `prod_key`, and `sandbox_key` over the life of the screen. Once a screen is published, the `prod_key` / `sandbox_key` values are what the Qonversion SDKs use at runtime.


# Segments
Source: https://documentation.qonversion.io/reference/v4/segments

Create rule-based user segments from properties and purchase history for targeting experiments, reports, and remote configs.

A **Segment** is a rule-based slice of your user base. Segments power audience targeting for experiments, no-code screens, remote config, and scheduled reports. v4 separates **user-defined segments** (fully editable) from **system segments** (managed by Qonversion).

## Key concepts

* **Rules** — Boolean combinations of predicates over user properties, purchases, and identity fields.
* **System segments** — Read-only, predefined segments (e.g., active subscribers, churned users).
* **Uses** — Segments can be referenced by experiments, scheduled reports, and automations.

## Condition shape

Each condition has the same four fields:

| Field        | Type    | Required | Description                                                                                                                   |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `metric`     | string  | yes      | Metric identifier. Common: `environment`, `client_uid`, `custom_uid`, `client_advertiser_id`, `renewable`, `target_platform`. |
| `comparator` | string  | yes      | One of `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`.                                                      |
| `value`      | string  | yes      | String-encoded value compared against the metric (cast to the metric's type server-side).                                     |
| `negate`     | boolean | no       | If `true`, the single rule matches when the comparison is false. Defaults to `false`.                                         |

Rules are joined with logical AND — **every** condition must hold for a user to fall into the segment.

`PUT /segments/{segment_id}` is a full replace: pass the complete condition set you want to keep, or `[]` to clear. Omit the field entirely to leave conditions untouched.

**Example create body:**

```json theme={null}
{
  "name": "EU prod renewables",
  "conditions": [
    { "metric": "environment", "comparator": "eq", "value": "prod" },
    { "metric": "renewable",   "comparator": "eq", "value": "1"    }
  ]
}
```

## Available endpoints

| Method | Endpoint                 | Description                     | Status |
| ------ | ------------------------ | ------------------------------- | ------ |
| GET    | `/segments`              | List segments                   | New    |
| POST   | `/segments`              | Create a segment                | New    |
| GET    | `/segments/system`       | List system segments            | New    |
| DELETE | `/segments/{segment_id}` | Delete a segment                | New    |
| GET    | `/segments/{segment_id}` | Get a segment                   | New    |
| PUT    | `/segments/{segment_id}` | Update a segment (full replace) | New    |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# User Properties
Source: https://documentation.qonversion.io/reference/v4/user-properties

Manage user-level attributes for segmentation and analytics

**User properties** are key–value attributes attached to a Qonversion user. They power segmentation, personalisation of no-code screens, and analytics. Qonversion-defined keys start with the `_q_` prefix (e.g., `_q_email`, `_q_custom_user_id`).

## Key concepts

* **Custom keys** — Any string identifier you choose. Keys must be 1–80 characters, match `^[-a-zA-Z0-9_.:]+$`, and contain at least one letter. Values are strings up to 120 bytes and must not contain `\n`, `\r`, `"`, or `'`.
* **System keys** — Reserved keys prefixed with `_q_` (e.g., `_q_email`, `_q_app_version`). Only pre-registered system keys are accepted; unknown `_q_*` keys are rejected. Keys starting with `_` but not `_q_` are forbidden.
* **Upsert** — `POST` replaces the value if the key already exists for the user.
* **Batch limits** — Up to 100 properties per request and up to 100 properties per user.
* **Partial success** — Invalid rows in a batch are reported per-key under `property_errors`; valid rows are applied and returned under `saved_properties`. The response is 200 as long as **at least one** row passes validation. If every row fails, the endpoint returns 400 without a per-key breakdown — retry with the offending rows removed to see the reasons.
* **No pagination** — The list response returns every stored property in one page; `has_more` is always `false`. `next_cursor` is omitted from the response.

## Available endpoints

| Method | Endpoint                      | Description                        | Status                              |
| ------ | ----------------------------- | ---------------------------------- | ----------------------------------- |
| GET    | `/users/{user_id}/properties` | List properties for a user         | Updated — [v3](/reference/overview) |
| POST   | `/users/{user_id}/properties` | Set (upsert) properties for a user | Updated — [v3](/reference/overview) |

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).


# Users
Source: https://documentation.qonversion.io/reference/v4/users

Retrieve Qonversion users and manage their properties, purchases, and entitlements

A **User** in Qonversion represents a single app user across platforms. Each user has a unique Qonversion User ID (prefixed with `QON_`) that is automatically generated by the SDK on first launch. Most user-scoped operations live under `/v4/users/{user_id}/…`.

## Key concepts

* **Qonversion User ID** — Auto-generated identifier (e.g., `QON_3af4c5b8a4d24f21b72e9d0c8aef9d4e`). The server emits a UUID with dashes stripped, so the suffix is always 32 lowercase hex characters.
* **Environment** — Each user belongs to either `prod` (production) or `sandbox` environment.
* **Identity** — Users can optionally be linked to your own user ID system via the [Identity API](/reference/v4/identities).
* **Sub-resources** — Properties, purchases, and entitlements live under dedicated endpoints, documented in [User Properties](/reference/v4/user-properties), [Purchases](/reference/v4/purchases), and [Entitlements](/reference/v4/entitlements).

## Available endpoints

| Method | Endpoint           | Description                                     | Status                              |
| ------ | ------------------ | ----------------------------------------------- | ----------------------------------- |
| POST   | `/users`           | Create a user (server generates the `QON_…` id) | New                                 |
| GET    | `/users/{user_id}` | Get a user                                      | Updated — [v3](/reference/overview) |

**v3 → v4 note:** v3's `POST /v3/users/{id}` accepted a client-supplied id. v4 standardises on server-issued ids across every resource — pass only the `environment` in the body, and use the returned `id` / `Location` for follow-up calls. Pair with an `Idempotency-Key` header to make retries safe.

## Authentication

All v4 endpoints require a **Secret Key**. See [Authentication](/reference/v4/authentication).