@qonversion/react-native-sdk 10.0.0-RC1

package/src/QonversionApi.ts

@@ -0,0 +1,318 @@
+import Entitlement from './dto/Entitlement';
+import Product from './dto/Product';
+import {UserPropertyKey, AttributionProvider} from './dto/enums';
+import Offerings from './dto/Offerings';
+import IntroEligibility from './dto/IntroEligibility';
+import User from './dto/User';
+import type {EntitlementsUpdateListener} from './dto/EntitlementsUpdateListener';
+import type {PromoPurchasesListener} from './dto/PromoPurchasesListener';
+import RemoteConfig from "./dto/RemoteConfig";
+import RemoteConfigList from "./dto/RemoteConfigList";
+import UserProperties from './dto/UserProperties';
+import PurchaseModel from './dto/PurchaseModel';
+import PurchaseUpdateModel from './dto/PurchaseUpdateModel';
+import PurchaseOptions from "./dto/PurchaseOptions";
+import SKProductDiscount from './dto/storeProducts/SKProductDiscount';
+import PromotionalOffer from './dto/PromotionalOffer';
+
+export interface QonversionApi {
+
+  /**
+   * Call this function to sync the subscriber data with the first launch when Qonversion is implemented.
+   */
+  syncHistoricalData(): void;
+
+  /**
+   * iOS only
+   * Contact us before you start using this function
+   * Call this function to sync purchases if you are using StoreKit2 and our SDK in Analytics mode.
+   */
+  syncStoreKit2Purchases(): void;
+
+  /**
+   * Call this function to check if the fallback file is accessible.
+   * @returns the promise with the flag that indicates whether Qonversion was able to read data from the fallback file or not.
+   */
+  isFallbackFileAccessible(): Promise<boolean>;
+
+  /**
+   * iOS only.
+   * Retrieve the promotional offer for the product if it exists.
+   * Make sure to call this function before displaying product details to the user.
+   * The generated signature for the promotional offer is valid for a single transaction.
+   * If the purchase fails, you need to call this function again to obtain a new promotional offer signature.
+   * Use this signature to complete the purchase through the purchase function, along with the purchase options object.
+   * @param product - product you want to purchase.
+   * @param discount - discount to create promotional offer signature.
+   * @returns the promise with the PromotionalOffer.
+   */
+
+  getPromotionalOffer(product: Product, discount: SKProductDiscount): Promise<PromotionalOffer | null>;
+
+  /**
+   * Make a purchase and validate it through server-to-server using Qonversion's Backend
+   * @param product product to purchase
+   * @param options additional options for the purchase process.
+   * @returns the promise with the user entitlements including the ones obtained by the purchase
+   *
+   * @see [Making Purchases](https://documentation.qonversion.io/docs/making-purchases)
+   */
+  purchaseProduct(product: Product, options?: PurchaseOptions | undefined): Promise<Map<string, Entitlement>>
+
+  /**
+   * Make a purchase and validate it through server-to-server using Qonversion's Backend.
+   *
+   * @deprecated Use {@link purchaseProduct} function instead.
+   * @param purchaseModel necessary information for purchase
+   * @returns the promise with the user entitlements including the ones obtained by the purchase
+   * @see [Making Purchases](https://documentation.qonversion.io/docs/making-purchases)
+   */
+  purchase(purchaseModel: PurchaseModel): Promise<Map<string, Entitlement>>;
+
+  /**
+   * Android only. Returns `null` if called on iOS.
+   *
+   * Update (upgrade/downgrade) subscription on Google Play Store and validate it through server-to-server using Qonversion's Backend.
+   *
+   * @deprecated Use {@link purchaseProduct} function instead.
+   * @param purchaseUpdateModel necessary information for purchase update
+   * @returns the promise with the user entitlements including updated ones.
+   * @see [Update policy](https://developer.android.com/google/play/billing/subscriptions#replacement-modes)
+   * @see [Making Purchases](https://documentation.qonversion.io/docs/making-purchases)
+   */
+  updatePurchase(purchaseUpdateModel: PurchaseUpdateModel): Promise<Map<string, Entitlement> | null>;
+
+  /**
+   * Returns Qonversion products in association with Apple and Google Play Store Products.
+   *
+   * @returns the promise with Qonversion products
+   */
+  products(): Promise<Map<string, Product>>;
+
+  /**
+   * Return Qonversion Offerings Object.
+   *
+   * An offering is a group of products that you can offer to a user on a given paywall based on your business logic.
+   * For example, you can offer one set of products on a paywall immediately after onboarding and another
+   * set of products with discounts later on if a user has not converted.
+   * Offerings allow changing the products offered remotely without releasing app updates.
+   *
+   * @returns the promise with Qonversion offerings
+   *
+   * @see [Offerings](https://qonversion.io/docs/offerings) for more details
+   */
+  offerings(): Promise<Offerings | null>;
+
+  /**
+   * You can check if a user is eligible for an introductory offer, including a free trial.
+   * You can show only a regular price for users who are not eligible for an introductory offer.
+   *
+   * @param ids products identifiers that must be checked
+   * @returns the promise with eligibility map
+   */
+  checkTrialIntroEligibility(ids: string[]): Promise<Map<string, IntroEligibility>>;
+
+  /**
+   * You need to call the checkEntitlements method to check if a user has the required entitlement.
+   *
+   * This method will check the user receipt and will return the current entitlements.
+   *
+   * @returns the promise with the entitlements
+   *
+   * If Apple or Google servers are not responding at the time of the request, Qonversion provides the latest
+   * entitlements' data from its database.
+   */
+  checkEntitlements(): Promise<Map<string, Entitlement>>;
+
+  /**
+   * Restores users purchases in your app, to maintain access to purchased content.
+   * Users sometimes need to restore purchased content, such as when they upgrade to a new phone.
+   *
+   * @returns the promise with the user entitlements
+   */
+  restore(): Promise<Map<string, Entitlement>>;
+
+  /**
+   * Android only. Does nothing if called on iOS.
+   *
+   * This method will send all purchases to the Qonversion backend. Call this every time when purchase is handled
+   * by your own implementation.
+   *
+   * **Warning!**
+   *
+   * This method works for Android only.
+   * It should only be called if you're using Qonversion SDK in observer mode.
+   *
+   * @see [Observer mode for Android SDK](https://documentation.qonversion.io/docs/observer-mode#android-sdk)
+   */
+  syncPurchases(): void;
+
+  /**
+   * Call this function to link a user to his unique ID in your system and share purchase data.
+   *
+   * @param userId unique user ID in your system
+   * @returns the promise with the information about the identified user.
+   */
+  identify(userId: string): Promise<User>;
+
+  /**
+   * Call this function to unlink a user from his unique ID in your system and his purchase data.
+   */
+  logout(): void;
+
+  /**
+   * This method returns information about the current Qonversion user.
+   * @returns the promise with the information about the user.
+   */
+  userInfo(): Promise<User>;
+
+  /**
+   * Sends your attribution {@link data} to the {@link provider}.
+   *
+   * @param data an object containing your attribution data
+   * @param provider the provider to which the data will be sent
+   */
+  attribution(data: Object, provider: AttributionProvider): void;
+
+  /**
+   * Sets Qonversion reserved user properties, like email or user id
+   *
+   * User properties are attributes you can set on a user level.
+   * You can send user properties to third party platforms as well as use them in Qonversion for customer segmentation
+   * and analytics.
+   *
+   * Note that using {@link UserPropertyKey.CUSTOM} here will do nothing.
+   * To set custom user property, use {@link setCustomUserProperty} method instead.
+   *
+   * @param key defined enum key that will be transformed to string.
+   * @param value property value.
+   *
+   * @see [documentation](https://documentation.qonversion.io/docs/user-properties)
+   */
+  setUserProperty(key: UserPropertyKey, value: string): void;
+
+  /**
+   * Adds custom user property.
+   *
+   * User properties are attributes you can set on a user level.
+   * You can send user properties to third party platforms as well as use them in Qonversion for customer segmentation
+   * and analytics.
+   *
+   * @param key custom user property key.
+   * @param value property value.
+   *
+   * @see [documentation](https://documentation.qonversion.io/docs/user-properties)
+   */
+  setCustomUserProperty(key: string, value: string): void;
+
+  /**
+   * This method returns all the properties, set for the current Qonversion user.
+   * All set properties are sent to the server with delay, so if you call
+   * this function right after setting some property, it may not be included
+   * in the result.
+   * @returns the promise with the user properties
+   */
+  userProperties(): Promise<UserProperties>;
+
+  /**
+   * Provide a listener to be notified about asynchronous user entitlements updates.
+   *
+   * Make sure you provide this listener for being up-to-date with the user entitlements.
+   * Else you can lose some important updates. Also, please, consider that this listener
+   * should live for the whole lifetime of the application.
+   *
+   * You may set entitlements listener both *after* Qonversion SDK initializing
+   * with {@link QonversionApi.setEntitlementsUpdateListener} and *while* Qonversion initializing
+   * with {@link Qonversion.initialize}.
+   *
+   * @param listener listener to be called when entitlements update
+   */
+  setEntitlementsUpdateListener(listener: EntitlementsUpdateListener): void;
+
+  /**
+   * iOS only. Does nothing if called on Android.
+   *
+   * 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.
+   */
+  collectAdvertisingId(): void;
+
+  /**
+   * iOS only. Does nothing if called on Android.
+   *
+   * Enable attribution collection from Apple Search Ads.
+   */
+  collectAppleSearchAdsAttribution(): void;
+
+  /**
+   * iOS only. Does nothing if called on Android.
+   *
+   * Set the delegate to handle promo purchases.
+   * The delegate is called when a promo purchase from the App Store happens.
+   * @param delegate delegate to be called when event happens.
+   */
+  setPromoPurchasesDelegate(delegate: PromoPurchasesListener): void;
+
+  /**
+   * iOS only. Does nothing if called on Android.
+   *
+   * On iOS 14.0+ shows up a sheet for users to redeem App Store offer codes.
+   */
+  presentCodeRedemptionSheet(): void;
+
+  /**
+   * Returns Qonversion remote config object by {@link contextKey} or default one if the key is not specified.
+   * Use this function to get the remote config with specific payload and experiment info.
+   * @returns the promise with the remote config.
+   */
+  remoteConfig(contextKey: string | undefined): Promise<RemoteConfig>
+
+  /**
+   * Returns Qonversion remote config objects for all existing context key (including empty one).
+   * Use this function to get the remote config with specific payload and experiment info.
+   * @returns the promise with the remote config list.
+   */
+  remoteConfigList(): Promise<RemoteConfigList>
+
+  /**
+   * Returns Qonversion remote config objects by a list of {@link contextKeys}.
+   * Use this function to get the remote config with specific payload and experiment info.
+   * @param contextKeys list of context keys to load remote configs for
+   * @param includeEmptyContextKey set to true if you want to include remote config with empty context key to the result
+   * @returns the promise with the remote config list.
+   */
+  remoteConfigListForContextKeys(contextKeys: string[], includeEmptyContextKey: boolean): Promise<RemoteConfigList>
+
+  /**
+   * This function should be used for the test purposes only. Do not forget to delete the usage of this function before the release.
+   * Use this function to attach the user to the experiment.
+   * @param experimentId identifier of the experiment
+   * @param groupId identifier of the experiment group
+   * @returns the promise for success result or throws an error otherwise.
+   */
+  attachUserToExperiment(experimentId: string, groupId: string): Promise<void>
+
+  /**
+   * This function should be used for the test purposes only. Do not forget to delete the usage of this function before the release.
+   * Use this function to detach the user from the experiment.
+   * @param experimentId identifier of the experiment
+   * @returns the promise for success result or throws an error otherwise.
+   */
+  detachUserFromExperiment(experimentId: string): Promise<void>
+
+  /**
+   * This function should be used for the test purposes only. Do not forget to delete the usage of this function before the release.
+   * Use this function to attach the user to the remote configuration.
+   * @param remoteConfigurationId identifier of the remote configuration
+   * @returns the promise for success result or throws an error otherwise.
+   */
+  attachUserToRemoteConfiguration(remoteConfigurationId: string): Promise<void>
+
+  /**
+   * This function should be used for the test purposes only. Do not forget to delete the usage of this function before the release.
+   * Use this function to detach the user from the remote configuration.
+   * @param remoteConfigurationId identifier of the remote configuration
+   * @returns the promise for success result or throws an error otherwise.
+   */
+  detachUserFromRemoteConfiguration(remoteConfigurationId: string): Promise<void>
+}

package/src/QonversionConfig.ts

@@ -0,0 +1,32 @@
+import {EntitlementsCacheLifetime, Environment, LaunchMode} from './dto/enums';
+import type {EntitlementsUpdateListener} from './dto/EntitlementsUpdateListener';
+
+class QonversionConfig {
+  readonly projectKey: string;
+  readonly launchMode: LaunchMode;
+  readonly environment: Environment;
+  readonly entitlementsCacheLifetime: EntitlementsCacheLifetime;
+  readonly entitlementsUpdateListener: EntitlementsUpdateListener | undefined;
+  readonly proxyUrl: string | undefined;
+  readonly kidsMode: boolean;
+
+  constructor(
+    projectKey: string,
+    launchMode: LaunchMode,
+    environment: Environment = Environment.PRODUCTION,
+    entitlementsCacheLifetime: EntitlementsCacheLifetime = EntitlementsCacheLifetime.MONTH,
+    entitlementsUpdateListener: EntitlementsUpdateListener | undefined = undefined,
+    proxyUrl: string | undefined,
+    kidsMode: boolean = false
+  ) {
+    this.projectKey = projectKey;
+    this.launchMode = launchMode;
+    this.environment = environment;
+    this.entitlementsCacheLifetime = entitlementsCacheLifetime;
+    this.entitlementsUpdateListener = entitlementsUpdateListener;
+    this.proxyUrl = proxyUrl;
+    this.kidsMode = kidsMode;
+  }
+}
+
+export default QonversionConfig;

package/src/QonversionConfigBuilder.ts

@@ -0,0 +1,102 @@
+import {EntitlementsCacheLifetime, Environment, LaunchMode} from './dto/enums';
+import type {EntitlementsUpdateListener} from './dto/EntitlementsUpdateListener';
+import QonversionConfig from './QonversionConfig';
+
+class QonversionConfigBuilder {
+  private readonly projectKey: string;
+  private readonly launchMode: LaunchMode;
+
+  constructor(projectKey: string, launchMode: LaunchMode) {
+    this.projectKey = projectKey;
+    this.launchMode = launchMode;
+  }
+
+  private environment: Environment = Environment.PRODUCTION;
+  private entitlementsCacheLifetime: EntitlementsCacheLifetime = EntitlementsCacheLifetime.MONTH;
+  private entitlementsUpdateListener: EntitlementsUpdateListener | undefined = undefined;
+  private proxyUrl: string | undefined = undefined;
+  private kidsMode: boolean = false;
+
+  /**
+   * Set current application {@link Environment}. Used to distinguish sandbox and production users.
+   *
+   * @param environment current environment.
+   * @return builder instance for chain calls.
+   */
+  setEnvironment(environment: Environment): QonversionConfigBuilder {
+    this.environment = environment;
+    return this;
+  }
+
+  /**
+   * Entitlements cache is used when there are problems with the Qonversion API
+   * or internet connection. If so, Qonversion will return the last successfully loaded
+   * entitlements. The current method allows you to configure how long that cache may be used.
+   * The default value is {@link EntitlementsCacheLifetime.MONTH}.
+   *
+   * @param lifetime desired entitlements cache lifetime duration
+   * @return builder instance for chain calls.
+   */
+  setEntitlementsCacheLifetime(lifetime: EntitlementsCacheLifetime): QonversionConfigBuilder {
+    this.entitlementsCacheLifetime = lifetime;
+    return this;
+  }
+
+  /**
+   * Provide a listener to be notified about asynchronous user entitlements updates.
+   *
+   * Make sure you provide this listener for being up-to-date with the user entitlements.
+   * Else you can lose some important updates. Also, please, consider that this listener
+   * should live for the whole lifetime of the application.
+   *
+   * @param entitlementsUpdateListener listener to be called when entitlements update.
+   * @return builder instance for chain calls.
+   */
+  setEntitlementsUpdateListener(entitlementsUpdateListener: EntitlementsUpdateListener): QonversionConfigBuilder {
+    this.entitlementsUpdateListener = entitlementsUpdateListener;
+    return this;
+  }
+
+  /**
+   * Provide a URL to your proxy server which will redirect all the requests from the app
+   * to our API. Please, contact us before using this feature.
+   *
+   * @param url your proxy server url
+   * @return builder instance for chain calls.
+   * @see [The documentation](https://documentation.qonversion.io/docs/custom-proxy-server-for-sdks)
+   */
+  setProxyURL(url: string): QonversionConfigBuilder {
+    this.proxyUrl = url;
+    return this;
+  }
+
+  /**
+   * Android only.
+   * Use this function to enable Qonversion SDK Kids mode.
+   * With this mode activated, our SDK does not collect any information that violates Google Children’s Privacy Policy.
+   * @return builder instance for chain calls.
+   */
+  enableKidsMode(): QonversionConfigBuilder {
+    this.kidsMode = true;
+    return this;
+  }
+
+  /**
+   * Generate {@link QonversionConfig} instance with all the provided configurations.
+   *
+   * @return the complete {@link QonversionConfig} instance.
+   */
+  build(): QonversionConfig {
+    return new QonversionConfig(
+      this.projectKey,
+      this.launchMode,
+      this.environment,
+      this.entitlementsCacheLifetime,
+      this.entitlementsUpdateListener,
+      this.proxyUrl,
+      this.kidsMode
+    )
+  }
+}
+
+export default QonversionConfigBuilder;

package/src/dto/Entitlement.ts

@@ -0,0 +1,57 @@
+import {EntitlementSource, EntitlementRenewState, EntitlementGrantType} from "./enums";
+import Transaction from "./Transaction";
+
+class Entitlement {
+  id: string;
+  productId: string;
+  isActive: boolean;
+  renewState: EntitlementRenewState;
+  source: EntitlementSource;
+  startedDate: Date;
+  renewsCount: number;
+  grantType: EntitlementGrantType;
+  transactions: Array<Transaction>;
+  expirationDate?: Date;
+  trialStartDate?: Date;
+  firstPurchaseDate?: Date;
+  lastPurchaseDate?: Date;
+  autoRenewDisableDate?: Date;
+  lastActivatedOfferCode?: string;
+
+  constructor(
+    id: string,
+    productId: string,
+    isActive: boolean,
+    renewState: EntitlementRenewState,
+    source: EntitlementSource,
+    startedTimestamp: number,
+    renewsCount: number,
+    grantType: EntitlementGrantType,
+    transactions: Array<Transaction>,
+    expirationTimestamp: number | undefined,
+    trialStartTimestamp: number | undefined,
+    firstPurchaseTimestamp: number | undefined,
+    lastPurchaseTimestamp: number | undefined,
+    autoRenewDisableTimestamp: number | undefined,
+    lastActivatedOfferCode: string | undefined,
+  ) {
+    this.id = id;
+    this.productId = productId;
+    this.isActive = isActive;
+    this.renewState = renewState;
+    this.source = source;
+    this.startedDate = new Date(startedTimestamp);
+    this.expirationDate = expirationTimestamp ? new Date(expirationTimestamp) : undefined;
+    this.renewsCount = renewsCount;
+    this.grantType = grantType;
+    this.transactions = transactions;
+    this.expirationDate = expirationTimestamp ? new Date(expirationTimestamp) : undefined;
+    this.trialStartDate = trialStartTimestamp ? new Date(trialStartTimestamp) : undefined;
+    this.firstPurchaseDate = firstPurchaseTimestamp ? new Date(firstPurchaseTimestamp) : undefined;
+    this.lastPurchaseDate = lastPurchaseTimestamp ? new Date(lastPurchaseTimestamp) : undefined;
+    this.autoRenewDisableDate = autoRenewDisableTimestamp ? new Date(autoRenewDisableTimestamp) : undefined;
+    this.lastActivatedOfferCode = lastActivatedOfferCode;
+  }
+}
+
+export default Entitlement;

package/src/dto/EntitlementsUpdateListener.ts

@@ -0,0 +1,11 @@
+import Entitlement from './Entitlement';
+
+export interface EntitlementsUpdateListener {
+
+  /**
+   * Called when entitlements update.
+   * For example, when pending purchases like SCA, Ask to buy, etc., happen.
+   * @param entitlements all the client's entitlements after update.
+   */
+  onEntitlementsUpdated(entitlements: Map<string, Entitlement>): void;
+}

package/src/dto/Experiment.ts

@@ -0,0 +1,15 @@
+import ExperimentGroup from "./ExperimentGroup";
+
+class Experiment {
+    id: string;
+    name: string;
+    group: ExperimentGroup;
+
+    constructor(id: string, name: string, group: ExperimentGroup) {
+        this.id = id;
+        this.name = name;
+        this.group = group;
+    }
+}
+
+export default Experiment;

package/src/dto/ExperimentGroup.ts

@@ -0,0 +1,15 @@
+import { ExperimentGroupType } from "./enums";
+
+class ExperimentGroup {
+    id: string;
+    name: string;
+    type: ExperimentGroupType;
+
+    constructor(id: string, name: string, type: ExperimentGroupType) {
+        this.id = id;
+        this.name = name;
+        this.type = type;
+    }
+}
+
+export default ExperimentGroup;

package/src/dto/IntroEligibility.ts

@@ -0,0 +1,11 @@
+import { IntroEligibilityStatus } from "./enums";
+
+class IntroEligibility {
+  status?: IntroEligibilityStatus;
+
+  constructor(status: IntroEligibilityStatus | undefined) {
+    this.status = status;
+  }
+}
+
+export default IntroEligibility;

package/src/dto/NoCodesAction.ts

@@ -0,0 +1,21 @@
+import {ActionType} from "./enums";
+import NoCodesError from './NoCodesError';
+
+class NoCodesAction {
+
+  type: ActionType;
+  value: Map<string, string | undefined> | undefined;
+  error: NoCodesError | undefined;
+
+  constructor(
+    type: ActionType,
+    value: Map<string, string | undefined> | undefined,
+    error: NoCodesError | undefined,
+  ) {
+    this.type = type;
+    this.value = value;
+    this.error = error;
+  }
+}
+
+export default NoCodesAction;

package/src/dto/NoCodesError.ts

@@ -0,0 +1,26 @@
+import {NoCodesErrorCode} from './enums';
+import QonversionError from './QonversionError';
+
+class NoCodesError {
+  code: NoCodesErrorCode;
+  description?: string | null;
+  additionalMessage?: string | null;
+  domain?: string | null;
+  error?: QonversionError;
+
+  constructor(
+    code: NoCodesErrorCode,
+    description?: string | null,
+    additionalMessage?: string | null,
+    domain?: string | null,
+    error?: QonversionError,
+  ) {
+    this.code = code;
+    this.domain = domain;
+    this.description = description;
+    this.additionalMessage = additionalMessage;
+    this.error = error;
+  }
+}
+
+export default NoCodesError;

package/src/dto/NoCodesListener.ts

@@ -0,0 +1,39 @@
+import NoCodesAction from './NoCodesAction';
+import NoCodesError from './NoCodesError';
+
+export interface NoCodesListener {
+    /**
+     * Called when No-Codes screen is shown
+     * @param id screen identifier
+     */
+    onScreenShown: (id: string) => void;
+
+    /**
+     * Called when No-Codes starts executing action
+     * @param action No-Codes action
+     */
+    onActionStartedExecuting: (action: NoCodesAction) => void;
+
+    /**
+     * Called when No-Codes fails to execute action
+     * @param action No-Codes action
+     */
+    onActionFailedToExecute: (action: NoCodesAction) => void;
+
+    /**
+     * Called when No-Codes finishes executing action
+     * @param action No-Codes action
+     */
+    onActionFinishedExecuting: (action: NoCodesAction) => void;
+
+    /**
+     * Called when No-Codes flow is finished
+     */
+    onFinished: () => void;
+
+    /**
+     * Called when No-Codes fails to load screen
+     * @param error error that occurred
+     */
+    onScreenFailedToLoad: (error: NoCodesError) => void;
+}

package/src/dto/Offering.ts

@@ -0,0 +1,20 @@
+import type { OfferingTags } from "./enums";
+import Product from "./Product";
+
+class Offering {
+  id: string;
+  tag: OfferingTags;
+  products: Array<Product>;
+
+  constructor(id: string, tag: OfferingTags, products: Product[]) {
+    this.id = id;
+    this.tag = tag;
+    this.products = products;
+  }
+
+  productForIdentifier(identifier: string): Product | undefined {
+    return this.products.find((object) => object.qonversionId === identifier);
+  }
+}
+
+export default Offering;