RCPurchases


@interface RCPurchases : NSObject

RCPurchases is the entry point for Purchases.framework. It should be instantiated as soon as your app has a unique user id for your user. This can be when a user logs in if you have accounts or on launch if you can generate a random user identifier.

Warning

Only one instance of RCPurchases should be instantiated at a time! Use a configure method to let the framework handle the singleton instance for you.
  • Enable automatic collection of Apple Search Ads attribution. Disabled by default

    Declaration

    Objective-C

    @property (class, nonatomic) BOOL automaticAppleSearchAdsAttributionCollection;
  • Deprecated

    use logLevel instead

    Enable debug logging. Useful for debugging issues with the lovely team @RevenueCat

    Declaration

    Objective-C

    @property (class, nonatomic) BOOL debugLogsEnabled;
  • Set a custom log handler for redirecting logs to your own logging system.

    By default, this sends Info, Warn, and Error messages. If you wish to receive Debug level messages, you must enable debug logs.

    Declaration

    Objective-C

    + (void)setLogHandler:(nonnull void (^)(RCLogLevel,
                                            NSString *_Nonnull))logHandler;
  • Used to set the log level. Useful for debugging issues with the lovely team @RevenueCat

    Declaration

    Objective-C

    @property (class, nonatomic) RCLogLevel logLevel;
  • Set this property to your proxy URL before configuring Purchases only if you’ve received a proxy key value from your RevenueCat contact.

    Declaration

    Objective-C

    @property (class, nonatomic, copy, nullable) NSURL *proxyURL;
  • Set this property to true only if you’re transitioning an existing Mac app from the Legacy Mac App Store into the Universal Store, and you’ve configured your RevenueCat app accordingly. Contact support before using this.

    Declaration

    Objective-C

    @property (class, nonatomic) BOOL forceUniversalAppStore;
  • Set this property to true only when testing the ask-to-buy / SCA purchases flow. More information: http://errors.rev.cat/ask-to-buy

    Declaration

    Objective-C

    @property (class, nonatomic) BOOL simulatesAskToBuyInSandbox;
  • Configures an instance of the Purchases SDK with a specified API key. The instance will be set as a singleton. You should access the singleton instance using [RCPurchases sharedPurchases]

    Note

    Use this initializer if your app does not have an account system. RCPurchases will generate a unique identifier for the current device and persist it to NSUserDefaults. This also affects the behavior of restoreTransactionsForAppStoreAccount.

    Declaration

    Objective-C

    + (nonnull instancetype)configureWithAPIKey:(nonnull NSString *)APIKey;

    Parameters

    APIKey

    The API Key generated for your app from https://app.revenuecat.com/

    Return Value

    An instantiated RCPurchases object that has been set as a singleton.

  • Configures an instance of the Purchases SDK with a specified API key and app user ID. The instance will be set as a singleton. You should access the singleton instance using [RCPurchases sharedPurchases]

    Note

    Best practice is to use a salted hash of your unique app user ids.

    Warning

    Use this initializer if you have your own user identifiers that you manage.

    Declaration

    Objective-C

    + (nonnull instancetype)configureWithAPIKey:(nonnull NSString *)APIKey
                                      appUserID:(nullable NSString *)appUserID;

    Parameters

    APIKey

    The API Key generated for your app from https://app.revenuecat.com/

    appUserID

    The unique app user id for this user. This user id will allow users to share their purchases and subscriptions across devices. Pass nil if you want RCPurchases to generate this for you.

    Return Value

    An instantiated RCPurchases object that has been set as a singleton.

  • Configures an instance of the Purchases SDK with a custom userDefaults. Use this constructor if you want to sync status across a shared container, such as between a host app and an extension. The instance of the Purchases SDK will be set as a singleton. You should access the singleton instance using [RCPurchases sharedPurchases]

    Declaration

    Objective-C

    + (nonnull instancetype)configureWithAPIKey:(nonnull NSString *)APIKey
                                      appUserID:(nullable NSString *)appUserID
                                   observerMode:(BOOL)observerMode;

    Parameters

    APIKey

    The API Key generated for your app from https://app.revenuecat.com/

    appUserID

    The unique app user id for this user. This user id will allow users to share their purchases and subscriptions across devices. Pass nil if you want RCPurchases to generate this for you.

    observerMode

    Set this to TRUE if you have your own IAP implementation and want to use only RevenueCat’s backend. Default is FALSE.

    Return Value

    An instantiated RCPurchases object that has been set as a singleton.

  • Configures an instance of the Purchases SDK with a custom userDefaults. Use this constructor if you want to sync status across a shared container, such as between a host app and an extension. The instance of the Purchases SDK will be set as a singleton. You should access the singleton instance using [RCPurchases sharedPurchases]

    Declaration

    Objective-C

    + (nonnull instancetype)configureWithAPIKey:(nonnull NSString *)APIKey
                                      appUserID:(nullable NSString *)appUserID
                                   observerMode:(BOOL)observerMode
                                   userDefaults:
                                       (nullable NSUserDefaults *)userDefaults;

    Parameters

    APIKey

    The API Key generated for your app from https://app.revenuecat.com/

    appUserID

    The unique app user id for this user. This user id will allow users to share their purchases and subscriptions across devices. Pass nil if you want RCPurchases to generate this for you.

    observerMode

    Set this to TRUE if you have your own IAP implementation and want to use only RevenueCat’s backend. Default is FALSE.

    userDefaults

    Custom userDefaults to use

    Return Value

    An instantiated RCPurchases object that has been set as a singleton.

  • Indicates whether the user is allowed to make payments.

    Declaration

    Objective-C

    + (BOOL)canMakePayments;
  • Declaration

    Objective-C

    @property (class, nonatomic, readonly) RCPurchases *_Nonnull sharedPurchases;

    Return Value

    A singleton RCPurchases object. Call this after a configure method to access the singleton. @note: If the SDK has not been configured, calls to sharedPurchases will raise an exception. Make sure to configure the SDK before making calls to sharedPurchases.

Configuration

  • Note

    True if the SDK has been configured, false otherwise. This property should only be used in special circumstances. If the shared instance has not been configured, calls made to it will raise an exception.

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) BOOL isConfigured;
  • Deprecated

    Configure behavior through the RevenueCat dashboard instead.

    Set this to true if you are passing in an appUserID but it is anonymous, this is true by default if you didn’t pass an appUserID If a user tries to purchase a product that is active on the current app store account, we will treat it as a restore and alias the new ID with the previous id. See https://docs.revenuecat.com/docs/user-ids

    Declaration

    Objective-C

    @property (nonatomic) BOOL allowSharingAppStoreAccount;
  • Default to YES, set this to NO if you are finishing transactions with your own StoreKit queue listener

    Declaration

    Objective-C

    @property (nonatomic) BOOL finishTransactions;
  • This version of the Purchases framework

    Declaration

    Objective-C

    + (nonnull NSString *)frameworkVersion;
  • Delegate for RCPurchases instance. The delegate is responsible for handling promotional product purchases and changes to purchaser information.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<RCPurchasesDelegate> delegate;

Identity

  • The appUserID used by RCPurchases. If not passed on initialization this will be generated and cached by RCPurchases.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSString *_Nonnull appUserID;
  • If the appUserID has been generated by RevenueCat

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isAnonymous;
  • Deprecated

    Use logIn instead.

    This function will alias two appUserIDs together.

    Declaration

    Objective-C

    - (void)createAlias:(nonnull NSString *)alias
        completionBlock:(nullable RCReceivePurchaserInfoBlock)completion;

    Parameters

    alias

    The new appUserID that should be linked to the currently identified appUserID

    completion

    An optional completion block called when the aliasing has been successful. This completion block will receive an error if there’s been one.

  • Deprecated

    Use logIn instead.

    This function will identify the current user with an appUserID. Typically this would be used after a logout to identify a new user without calling configure.

    Declaration

    Objective-C

    - (void)identify:(nonnull NSString *)appUserID
        completionBlock:(nullable RCReceivePurchaserInfoBlock)completion;

    Parameters

    appUserID

    The appUserID that should be linked to the current user.

  • Deprecated

    Use logOut instead.

    Resets the Purchases client clearing the saved appUserID. This will generate a random user id and save it in the cache.

    Declaration

    Objective-C

    - (void)resetWithCompletionBlock:
        (nullable RCReceivePurchaserInfoBlock)completion;
  • This function will logIn the current user with an appUserID.

    Declaration

    Objective-C

    - (void)logIn:(nonnull NSString *)appUserID
        completionBlock:(nonnull void (^)(RCPurchaserInfo *_Nullable, BOOL,
                                          NSError *_Nullable))completion;

    Parameters

    appUserID

    The appUserID that should be linked to the current user. The callback will be called with the latest PurchaserInfo for the user, as well as a boolean indicating whether the user was created for the first time in the RevenueCat backend. See https://docs.revenuecat.com/docs/user-ids

  • Logs out the Purchases client clearing the saved appUserID. This will generate a random user id and save it in the cache. If this method is called and the current user is anonymous, it will return an error. See https://docs.revenuecat.com/docs/user-ids

    Declaration

    Objective-C

    - (void)logOutWithCompletionBlock:
        (nullable RCReceivePurchaserInfoBlock)completion;

Attribution

Purchases

  • Get latest available purchaser info.

    Declaration

    Objective-C

    - (void)purchaserInfoWithCompletionBlock:
        (nonnull RCReceivePurchaserInfoBlock)completion;

    Parameters

    completion

    A completion block called when purchaser info is available and not stale. Called immediately if purchaser info is cached. Purchaser info can be nil if an error occurred.

  • Fetch the configured offerings for this users. Offerings allows you to configure your in-app products via RevenueCat and greatly simplifies management. See the guide (https://docs.revenuecat.com/entitlements) for more info.

    Offerings will be fetched and cached on instantiation so that, by the time they are needed, your prices are loaded for your purchase flow. Time is money.

    Declaration

    Objective-C

    - (void)offeringsWithCompletionBlock:
        (nonnull RCReceiveOfferingsBlock)completion;

    Parameters

    completion

    A completion block called when offerings are available. Called immediately if offerings are cached. Offerings will be nil if an error occurred.

  • Fetches the SKProducts for your IAPs for given productIdentifiers. Use this method if you aren’t using -offeringsWithCompletionBlock:. You should use offerings though.

    Note

    completion may be called without SKProducts that you are expecting. This is usually caused by iTunesConnect configuration errors. Ensure your IAPs have the “Ready to Submit” status in iTunesConnect. Also ensure that you have an active developer program subscription and you have signed the latest paid application agreements. If you’re having trouble see: https://www.revenuecat.com/2018/10/11/configuring-in-app-products-is-hard

    Declaration

    Objective-C

    - (void)productsWithIdentifiers:
                (nonnull NSArray<NSString *> *)productIdentifiers
                    completionBlock:(nonnull RCReceiveProductsBlock)completion;

    Parameters

    productIdentifiers

    A set of product identifiers for in app purchases setup via iTunesConnect. This should be either hard coded in your application, from a file, or from a custom endpoint if you want to be able to deploy new IAPs without an app update.

    completion

    An @escaping callback that is called with the loaded products. If the fetch fails for any reason it will return an empty array.

  • Use this function if you are not using the Offerings system to purchase an SKProduct. If you are using the Offerings system, use -[RCPurchases purchasePackage:withCompletionBlock] instead.

    Call this method when a user has decided to purchase a product. Only call this in direct response to user input.

    From here Purchases will handle the purchase with StoreKit and call the RCPurchaseCompletedBlock.

    Note

    You do not need to finish the transaction yourself in the completion callback, Purchases will handle this for you.

    Declaration

    Objective-C

    - (void)purchaseProduct:(nonnull SKProduct *)product
        withCompletionBlock:(nonnull RCPurchaseCompletedBlock)completion;

    Parameters

    product

    The SKProduct the user intends to purchase

    completion

    A completion block that is called when the purchase completes. If the purchase was successful there will be a SKPaymentTransaction and a RCPurchaserInfo. If the purchase was not successful, there will be an NSError. If the user cancelled, userCancelled will be YES.

  • Purchase the passed RCPackage.

    Call this method when a user has decided to purchase a product. Only call this in direct response to user input.

    From here Purchases will handle the purchase with StoreKit and call the RCPurchaseCompletedBlock.

    Note

    You do not need to finish the transaction yourself in the completion callback, Purchases will handle this for you.

    Declaration

    Objective-C

    - (void)purchasePackage:(nonnull RCPackage *)package
        withCompletionBlock:(nonnull RCPurchaseCompletedBlock)completion;

    Parameters

    package

    The RCPackage the user intends to purchase

    completion

    A completion block that is called when the purchase completes. If the purchase was successful there will be a SKPaymentTransaction and a RCPurchaserInfo. If the purchase was not successful, there will be an NSError. If the user cancelled, userCancelled will be YES.

  • This method will post all purchases associated with the current App Store account to RevenueCat and become associated with the current appUserID. If the receipt is being used by an existing user, the current appUserID will be aliased together with the appUserID of the existing user. Going forward, either appUserID will be able to reference the same user.

    You shouldn’t use this method if you have your own account system. In that case “restoration” is provided by your app passing the same appUserId used to purchase originally.

    Note

    This may force your users to enter the App Store password so should only be performed on request of the user. Typically with a button in settings or near your purchase UI. Use syncPurchasesWithCompletionBlock if you need to restore transactions programmatically.

    Declaration

    Objective-C

    - (void)restoreTransactionsWithCompletionBlock:
        (nullable RCReceivePurchaserInfoBlock)completion;
  • This method will post all purchases associated with the current App Store account to RevenueCat and become associated with the current appUserID. If the receipt is being used by an existing user, the current appUserID will be aliased together with the appUserID of the existing user. Going forward, either appUserID will be able to reference the same user.

    Warning

    This function should only be called if you’re not calling any purchase method.

    Note

    This method will not trigger a login prompt from App Store. However, if the receipt currently on the device does not contain subscriptions, but the user has made subscription purchases, this method won’t be able to restore them. Use restoreTransactionsWithCompletionBlock to cover those cases.

    Declaration

    Objective-C

    - (void)syncPurchasesWithCompletionBlock:
        (nullable RCReceivePurchaserInfoBlock)completion;
  • Computes whether or not a user is eligible for the introductory pricing period of a given product. 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).

    Note

    Subscription groups are automatically collected for determining eligibility. If RevenueCat can’t definitively compute the eligibilty, most likely because of missing group information, it will return RCIntroEligibilityStatusUnknown. The best course of action on unknown status is to display the non-intro pricing, to not create a misleading situation. To avoid this, make sure you are testing with the latest version of iOS so that the subscription group can be collected by the SDK.

    Declaration

    Objective-C

    - (void)checkTrialOrIntroductoryPriceEligibility:
                (nonnull NSArray<NSString *> *)productIdentifiers
                                     completionBlock:
                                         (nonnull RCReceiveIntroEligibilityBlock)
                                             receiveEligibility;

    Parameters

    productIdentifiers

    Array of product identifiers for which you want to compute eligibility

    receiveEligibility

    A block that receives a dictionary of product_id -> RCIntroEligibility.

  • Use this function to retrieve the SKPaymentDiscount for a given SKProduct.

    Declaration

    Objective-C

    - (void)paymentDiscountForProductDiscount:(nonnull SKProductDiscount *)discount
                                      product:(nonnull SKProduct *)product
                                   completion:
                                       (nonnull RCPaymentDiscountBlock)completion;

    Parameters

    discount

    The SKProductDiscount to apply to the product.

    product

    The SKProduct the user intends to purchase.

    completion

    A completion block that is called when the SKPaymentDiscount is returned. If it was not successful, there will be an NSError.

  • Use this function if you are not using the Offerings system to purchase an SKProduct with an applied SKPaymentDiscount. If you are using the Offerings system, use -[RCPurchases purchasePackage:withDiscount:withCompletionBlock] instead.

    Call this method when a user has decided to purchase a product with an applied discount. Only call this in direct response to user input.

    From here Purchases will handle the purchase with StoreKit and call the RCPurchaseCompletedBlock.

    Note

    You do not need to finish the transaction yourself in the completion callback, Purchases will handle this for you.

    Declaration

    Objective-C

    - (void)purchaseProduct:(nonnull SKProduct *)product
               withDiscount:(nonnull SKPaymentDiscount *)discount
            completionBlock:(nonnull RCPurchaseCompletedBlock)completion;

    Parameters

    product

    The SKProduct the user intends to purchase

    discount

    The SKPaymentDiscount to apply to the purchase

    completion

    A completion block that is called when the purchase completes. If the purchase was successful there will be a SKPaymentTransaction and a RCPurchaserInfo. If the purchase was not successful, there will be an NSError. If the user cancelled, userCancelled will be YES.

  • Purchase the passed RCPackage.

    Call this method when a user has decided to purchase a product with an applied discount. Only call this in direct response to user input.

    From here Purchases will handle the purchase with StoreKit and call the RCPurchaseCompletedBlock.

    Note

    You do not need to finish the transaction yourself in the completion callback, Purchases will handle this for you.

    Declaration

    Objective-C

    - (void)purchasePackage:(nonnull RCPackage *)package
               withDiscount:(nonnull SKPaymentDiscount *)discount
            completionBlock:(nonnull RCPurchaseCompletedBlock)completion;

    Parameters

    package

    The RCPackage the user intends to purchase

    discount

    The SKPaymentDiscount to apply to the purchase

    completion

    A completion block that is called when the purchase completes. If the purchase was successful there will be a SKPaymentTransaction and a RCPurchaserInfo. If the purchase was not successful, there will be an NSError. If the user cancelled, userCancelled will be YES.

  • Invalidates the cache for purchaser information.

    Most apps will not need to use this method; invalidating the cache can leave your app in an invalid state. Refer to https://docs.revenuecat.com/docs/purchaserinfo#section-get-user-information for more information on using the cache properly.

    This is useful for cases where purchaser information might have been updated outside of the app, like if a promotional subscription is granted through the RevenueCat dashboard.

    Declaration

    Objective-C

    - (void)invalidatePurchaserInfoCache;
  • Displays a sheet that enables users to redeem subscription offer codes that you generated in App Store Connect.

    Declaration

    Objective-C

    - (void)presentCodeRedemptionSheet;

Subscriber Attributes

  • Subscriber attributes are useful for storing additional, structured information on a user. Since attributes are writable using a public key they should not be used for managing secure or sensitive information such as subscription status, coins, etc.

    Key names starting with “$” are reserved names used by RevenueCat. For a full list of key restrictions refer to our guide: https://docs.revenuecat.com/docs/subscriber-attributes

    Declaration

    Objective-C

    - (void)setAttributes:
        (nonnull NSDictionary<NSString *, NSString *> *)attributes;

    Parameters

    attributes

    Map of attributes by key. Set the value as an empty string to delete an attribute.

  • Subscriber attribute associated with the email address for the user

    Declaration

    Objective-C

    - (void)setEmail:(nullable NSString *)email;

    Parameters

    email

    Empty String or nil will delete the subscriber attribute.

  • Subscriber attribute associated with the phone number for the user

    Declaration

    Objective-C

    - (void)setPhoneNumber:(nullable NSString *)phoneNumber;

    Parameters

    phoneNumber

    Empty String or nil will delete the subscriber attribute.

  • Subscriber attribute associated with the display name for the user

    Declaration

    Objective-C

    - (void)setDisplayName:(nullable NSString *)displayName;

    Parameters

    displayName

    Empty String or nil will delete the subscriber attribute.

  • Subscriber attribute associated with the push token for the user

    Declaration

    Objective-C

    - (void)setPushToken:(nullable NSData *)pushToken;

    Parameters

    pushToken

    nil will delete the subscriber attribute.

  • Subscriber attribute associated with the Adjust Id for the user Required for the RevenueCat Adjust integration

    Declaration

    Objective-C

    - (void)setAdjustID:(nullable NSString *)adjustID;

    Parameters

    adjustID

    nil will delete the subscriber attribute

  • Subscriber attribute associated with the Appsflyer Id for the user Required for the RevenueCat Appsflyer integration

    Declaration

    Objective-C

    - (void)setAppsflyerID:(nullable NSString *)appsflyerID;

    Parameters

    appsflyerID

    nil will delete the subscriber attribute

  • Subscriber attribute associated with the Facebook SDK Anonymous Id for the user Recommended for the RevenueCat Facebook integration

    Declaration

    Objective-C

    - (void)setFBAnonymousID:(nullable NSString *)fbAnonymousID;

    Parameters

    fbAnonymousID

    nil will delete the subscriber attribute

  • Subscriber attribute associated with the mParticle Id for the user Recommended for the RevenueCat mParticle integration

    Declaration

    Objective-C

    - (void)setMparticleID:(nullable NSString *)mparticleID;

    Parameters

    mparticleID

    nil will delete the subscriber attribute

  • Subscriber attribute associated with the OneSignal Player Id for the user Required for the RevenueCat OneSignal integration

    Declaration

    Objective-C

    - (void)setOnesignalID:(nullable NSString *)onesignalID;

    Parameters

    onesignalID

    nil will delete the subscriber attribute

  • Subscriber attribute associated with the install media source for the user

    Declaration

    Objective-C

    - (void)setMediaSource:(nullable NSString *)mediaSource;

    Parameters

    mediaSource

    nil will delete the subscriber attribute.

  • Subscriber attribute associated with the install campaign for the user

    Declaration

    Objective-C

    - (void)setCampaign:(nullable NSString *)campaign;

    Parameters

    campaign

    nil will delete the subscriber attribute.

  • Subscriber attribute associated with the install ad group for the user

    Declaration

    Objective-C

    - (void)setAdGroup:(nullable NSString *)adGroup;

    Parameters

    adGroup

    nil will delete the subscriber attribute.

  • Subscriber attribute associated with the install ad for the user

    Declaration

    Objective-C

    - (void)setAd:(nullable NSString *)ad;

    Parameters

    ad

    nil will delete the subscriber attribute.

  • Subscriber attribute associated with the install keyword for the user

    Declaration

    Objective-C

    - (void)setKeyword:(nullable NSString *)keyword;

    Parameters

    keyword

    nil will delete the subscriber attribute.

  • Subscriber attribute associated with the install ad creative for the user

    Declaration

    Objective-C

    - (void)setCreative:(nullable NSString *)creative;

    Parameters

    creative

    nil will delete the subscriber attribute.

  • Automatically collect subscriber attributes associated with the device identifiers $idfa, $idfv, $ip

    Declaration

    Objective-C

    - (void)collectDeviceIdentifiers;