Web SDK
Send Web purchases data to manage cross-platform user access: Web, iOS, Android.
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 ma |
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
For now, Qonversion Web SDK accepts only Stripe purchases. We are working on supporting more billing providers.
To send the purchase to Qonversion after you receive a successful response from Stripe, call the following method and provide the received data.
const purchase = await qonversionInstance.sendStripePurchase(stripeData);
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.
Updated 9 months ago