Web SDK

Install

Qonversion SDK package is available on npm.

npm install @qonversion/web-sdk

yarn add @qonversion/web-sdk

You can check the implementation details of the Web SDK here.

Launching the SDK

First of all, you need to create the launching configuration. It can be made using the QonversionConfigBuilder class as follows.

import {QonversionConfigBuilder} from '@qonversion/web-sdk';

...

const config = new QonversionConfigBuilder(projectKey).build();

You can also provide additional configuration if necessary.

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();

After the configuration is prepared, you should initialize the SDK using it.

import Qonversion from '@qonversion/web-sdk';

...

const qonversionInstance = Qonversion.initialize(config);

Now you are ready to use the SDK. All the work with the SDK is done via the initialized instance.

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();

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.

qonversionInstance.setLogTag('NewCustomLogTagForMyApp');

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. We defined some common case properties and provided API for adding them:

import {UserPropertyKey} from '@qonversion/web-sdk';

...

qonversionInstance.setUserProperty(UserPropertyKey.CustomUserId, 'yourSideUserId');

You can also provide custom properties using the following method.

qonversionInstance.setCustomUserProperty('liked-app', 'yes');

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.

import {UserPropertiesBuilder} from '@qonversion/web-sdk';

...

const properties = new UserPropertiesBuilder()
  .setCustomUserId('yourSideUserId')
  .setEmail('[email protected]')
  .setCustomUserProperty('liked-app', 'yes')
  .build();

qonversionInstance.setUserProperties(properties);

To get all the properties set to a user, you can call the userProperties method, that returns an object, containing all the properties.

const userProperties = await Qonversion.getSharedInstance().userProperties();
userProperties.properties.forEach(userProperty =>
  console.log('Property key: ' + userProperty.key + ', value: ' + userProperty.value)
);

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 and Paddle 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.

const purchase = await qonversionInstance.sendStripePurchase(stripeData);

// 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'
});

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 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.

const entitlements = await qonversionInstance.entitlements();

Identity

User Identity allows cross-device & cross-platform user identification and access management. You can read more about it here. When a user logs into his account, call identify().

await qonversionInstance.identify('your_custom_user_id');

And when a user logs out call logout()

await qonversionInstance.logout();

Consider looking at the examples here 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 or Paddle and mapping their products into your Qonversion entitlements.

Overview

Get Started

Testing

Features

No-Code Builder

Remote Config

Experiments

Platform Resources

Stores Setup

SDK Migration Guides

AI-Ready

API Reference Guide

API Reference Guide v4

Install

Launching the SDK

Properties

Purchases

Entitlements

Identity

Next steps

​Install

​Launching the SDK

​Properties

​Purchases

​Entitlements

​Identity

​Next steps

Install

Launching the SDK

Properties

Purchases

Entitlements

Identity

Next steps