npm package: @joinflux/capacitor-subscriptions
Description: Subscriptions via Revenue Cat
Author: Rafael Nicdao
Latest version: 1.4.0

# @joinflux/capacitor-subscriptions

Subscriptions via Revenue Cat

## Versioning

- Use version 1.x.x for Capacitor 5 support
- Use version 0.x.x for Capacitor 4 support

## Install

```bash
npm install @joinflux/capacitor-subscriptions
npx cap sync
```

## API

<docgen-index>

* [`configure(...)`](#configure)
* [`logIn(...)`](#login)
* [`logOut()`](#logout)
* [`getProduct(...)`](#getproduct)
* [`getEligibleOffer(...)`](#geteligibleoffer)
* [`purchaseProduct(...)`](#purchaseproduct)
* [`checkIntroOfferEligibility(...)`](#checkintrooffereligibility)
* [`syncPurchases()`](#syncpurchases)
* [`setDeviceIdentifiers()`](#setdeviceidentifiers)
* [`setAdvertisementAttribution(...)`](#setadvertisementattribution)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### configure(...)

```typescript
configure(options: { apiKey: string; appUserID?: string; }) => void
```

`configure` initializes the plugin

| Param         | Type                                                 |
| ------------- | ---------------------------------------------------- |
| **`options`** | <code>{ apiKey: string; appUserID?: string; }</code> |

--------------------


### logIn(...)

```typescript
logIn(options: { userId: string; email?: string; displayName?: string; }) => Promise<void>
```

`logIn` identifies the app user (a user is initially 'anonymous' user on app
startup). The user's ID is required but email and display name are optional
(just for convenience - saves us from having to look up these details in other systems).
NOTE: The email and display name are only updated after the user ID is successfully set
and empty strings are ignored/treated the same as `undefined`.

| Param         | Type                                                                   |
| ------------- | ---------------------------------------------------------------------- |
| **`options`** | <code>{ userId: string; email?: string; displayName?: string; }</code> |

--------------------


### logOut()

```typescript
logOut() => Promise<void>
```

`logOut` logs out the currently logged in user

--------------------


### getProduct(...)

```typescript
getProduct(options: { id: string; }) => Promise<Product | undefined>
```

`getProduct` retrives the product with the specified `id`

| Param         | Type                         |
| ------------- | ---------------------------- |
| **`options`** | <code>{ id: string; }</code> |

**Returns:** <code>Promise&lt;<a href="#product">Product</a>&gt;</code>

--------------------


### getEligibleOffer(...)

```typescript
getEligibleOffer(options: { productId: string; offerId: string; }) => Promise<Offer | undefined>
```

`getEligibleOffer` returns the offer with the specified ID,
for the specified product that the user is eligible for
- In IOS, searches through Promotional Offers
- In Android, searches through Offers with a discounted price (excludes free trial)

| Param         | Type                                                 |
| ------------- | ---------------------------------------------------- |
| **`options`** | <code>{ productId: string; offerId: string; }</code> |

**Returns:** <code>Promise&lt;<a href="#offer">Offer</a>&gt;</code>

--------------------


### purchaseProduct(...)

```typescript
purchaseProduct(options: { productId: string; offerId?: string; }) => Promise<void>
```

`purchaseProduct` initiates the native store purchase (i.e. triggers the native pop-up).

| Param         | Type                                                  |
| ------------- | ----------------------------------------------------- |
| **`options`** | <code>{ productId: string; offerId?: string; }</code> |

--------------------


### checkIntroOfferEligibility(...)

```typescript
checkIntroOfferEligibility(options: { productId: string; }) => Promise<IntroEligibility>
```

`checkIntroOfferEligibility` computes whether or not a user is eligible for the introductory pricing period of a given product.
IOS:
You should use this method to determine whether or not you show the user the normal product price or the
introductory price. This also applies to trials (trials are considered a type of introductory pricing).

| Param         | Type                                |
| ------------- | ----------------------------------- |
| **`options`** | <code>{ productId: string; }</code> |

**Returns:** <code>Promise&lt;<a href="#introeligibility">IntroEligibility</a>&gt;</code>

--------------------


### syncPurchases()

```typescript
syncPurchases() => Promise<void>
```

`syncPurchases` synchronizes the current App Store/Play Store account's purchases/transactions to RevenueCat.
This is particularly useful for purchases/transactions done outside the app.
For example: redeeming an IOS <a href="#offer">Offer</a> code in the App Store.
See https://www.revenuecat.com/docs/migrating-existing-subscriptions#client-side-migration for more info.

NOTE that `syncPurchases` should only be called when necessary due to potential pit falls such as unintentionally
aliasing accounts.
See https://www.revenuecat.com/docs/restoring-purchases#syncpurchases-considerations for more info.

--------------------


### setDeviceIdentifiers()

```typescript
setDeviceIdentifiers() => Promise<void>
```

`setDeviceIdentifiers` automatically collects then sets the user's device identifiers (such as Google Ad ID, IOS IDFA/IDFV, etc.)
in their Subscriber attributes. This is primarily for ad/marketing attribution purposes.
Note that for IOS 14.5+, if the user allows the App Tracking, this method should be called again to update the user's IDFA in RevenueCat.

--------------------


### setAdvertisementAttribution(...)

```typescript
setAdvertisementAttribution(data: AdvertisementAttribution) => Promise<void>
```

`setAdvertisementAttribution` sets the advertisement-related attribution data in the user's Subscriber attributes.
Note that if a property is not included (or `undefined`) or is an empty string, it is not updated in RevenueCat.

| Param      | Type                                                                                                                                                                               |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`data`** | <code><a href="#partial">Partial</a>&lt;{ appsFlyerId: string; mediaSource: string; campaign: string; adGroup: string; ad: string; keyword: string; creative: string; }&gt;</code> |

--------------------


### Interfaces


#### Product

| Prop              | Type                                                      | Description                                                                                                                          |
| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **`identifier`**  | <code>string</code>                                       | <a href="#product">Product</a> Id.                                                                                                   |
| **`price`**       | <code>number</code>                                       | Price of the product in the local currency.                                                                                          |
| **`priceString`** | <code>string</code>                                       | Formatted price of the item, including its currency sign, such as €3.99.                                                             |
| **`introPrice`**  | <code><a href="#introprice">IntroPrice</a> \| null</code> | Introductory price. - IOS: corresponds to the introductory offer (if it exists) - Android: corresponds to the first free trial offer |


#### IntroPrice

| Prop                      | Type                | Description                                                                                      |
| ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| **`price`**               | <code>number</code> | Price in the local currency.                                                                     |
| **`priceString`**         | <code>string</code> | Formatted price, including its currency sign, such as €3.99.                                     |
| **`cycles`**              | <code>number</code> | Number of subscription billing periods for which the user will be given the discount, such as 3. |
| **`period`**              | <code>string</code> | Billing period of the discount, specified in ISO 8601 format.                                    |
| **`periodUnit`**          | <code>string</code> | Unit for the billing period of the discount, can be DAY, WEEK, MONTH or YEAR.                    |
| **`periodNumberOfUnits`** | <code>number</code> | Number of units for the billing period of the discount.                                          |


#### Offer

| Prop                      | Type                | Description                                                                                      |
| ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| **`identifier`**          | <code>string</code> | Identifier of the discount.                                                                      |
| **`price`**               | <code>number</code> | Price in the local currency.                                                                     |
| **`priceString`**         | <code>string</code> | Formatted price, including its currency sign, such as €3.99.                                     |
| **`cycles`**              | <code>number</code> | Number of subscription billing periods for which the user will be given the discount, such as 3. |
| **`period`**              | <code>string</code> | Billing period of the discount, specified in ISO 8601 format.                                    |
| **`periodUnit`**          | <code>string</code> | Unit for the billing period of the discount, can be DAY, WEEK, MONTH or YEAR.                    |
| **`periodNumberOfUnits`** | <code>number</code> | Number of units for the billing period of the discount.                                          |


#### IntroEligibility

Holds the introductory price status

| Prop              | Type                                                                          | Description                               |
| ----------------- | ----------------------------------------------------------------------------- | ----------------------------------------- |
| **`status`**      | <code><a href="#intro_eligibility_status">INTRO_ELIGIBILITY_STATUS</a></code> | The introductory price eligibility status |
| **`description`** | <code>string</code>                                                           | Description of the status                 |


### Type Aliases


#### AdvertisementAttribution

<a href="#advertisementattribution">`AdvertisementAttribution`</a> represents various ad properties for conversion attribution.

<code><a href="#partial">Partial</a>&lt;{ appsFlyerId: string; mediaSource: string; campaign: string; adGroup: string; ad: string; keyword: string; creative: string; }&gt;</code>


#### Partial

Make all properties in T optional

<code>{ [P in keyof T]?: T[P]; }</code>


### Enums


#### INTRO_ELIGIBILITY_STATUS

| Members                                              | Value          | Description                                                                  |
| ---------------------------------------------------- | -------------- | ---------------------------------------------------------------------------- |
| **`INTRO_ELIGIBILITY_STATUS_UNKNOWN`**               | <code>0</code> | RevenueCat doesn't have enough information to determine eligibility.         |
| **`INTRO_ELIGIBILITY_STATUS_INELIGIBLE`**            |                | The user is not eligible for a free trial or intro pricing for this product. |
| **`INTRO_ELIGIBILITY_STATUS_ELIGIBLE`**              |                | The user is eligible for a free trial or intro pricing for this product.     |
| **`INTRO_ELIGIBILITY_STATUS_NO_INTRO_OFFER_EXISTS`** |                | There is no free trial or intro pricing for this product.                    |

</docgen-api>