checkEntitlements() method to decide what premium content to unlock. Read more about creating and using entitlements in 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: for example, after a user subscribes in your iOS app, you can check the same entitlements in your Android or web apps.
The Qonversion SDK caches product and entitlement data, so entitlements are still available immediately when the internet connection is lost or the server is delayed.
An entitlement object is returned only if the user has made a purchase, or you granted the entitlement manually through the Customer tab or the Grant Entitlement API. Otherwise
checkEntitlements() returns an empty result — an empty result means the user has no entitlements, not an error.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
}
}
}
[[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;
}
}
}];
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
}
});
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
}
})
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);
}
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
}
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());
}
});
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
}
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
}
The Entitlement object
Each value in theentitlements 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 thetransactions 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. |