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 toNSUserDefaults
. This also affects the behavior ofrestoreTransactionsForAppStoreAccount
.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. -
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 dangerousSettings:(nullable RCDangerousSettings *)dangerousSettings;
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
dangerousSettings
Only use a Dangerous Setting if suggested by RevenueCat support team.
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.
-
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;
-
The
appUserID
used byRCPurchases
. If not passed on initialization this will be generated and cached byRCPurchases
.Declaration
Objective-C
@property (nonatomic, readonly) NSString *_Nonnull appUserID;
-
If the
appUserID
has been generated by RevenueCatDeclaration
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;
-
Deprecated
Use the set
functions instead. Send your attribution data to RevenueCat so you can track the revenue generated by your different campaigns.
Declaration
Objective-C
+ (void)addAttributionData:(nonnull NSDictionary *)data fromNetwork:(RCAttributionNetwork)network;
Parameters
data
Dictionary provided by the network. See https://docs.revenuecat.com/docs/attribution
network
Enum for the network the data is coming from, see
RCAttributionNetwork
for supported networks -
Deprecated
Use the set
functions instead. Send your attribution data to RevenueCat so you can track the revenue generated by your different campaigns.
Declaration
Objective-C
+ (void)addAttributionData:(nonnull NSDictionary *)data fromNetwork:(RCAttributionNetwork)network forNetworkUserId:(nullable NSString *)networkUserId;
Parameters
data
Dictionary provided by the network. See https://docs.revenuecat.com/docs/attribution
network
Enum for the network the data is coming from, see
RCAttributionNetwork
for supported networksnetworkUserId
User Id that should be sent to the network. Default is the current App User Id
-
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 givenproductIdentifiers
. Use this method if you aren’t using-offeringsWithCompletionBlock:
. You should use offerings though.Note
completion
may be called withoutSKProduct
s 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-hardDeclaration
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 withStoreKit
and call theRCPurchaseCompletedBlock
.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 purchasecompletion
A completion block that is called when the purchase completes. If the purchase was successful there will be a
SKPaymentTransaction
and aRCPurchaserInfo
. If the purchase was not successful, there will be anNSError
. If the user cancelled,userCancelled
will beYES
. -
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 withStoreKit
and call theRCPurchaseCompletedBlock
.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 purchasecompletion
A completion block that is called when the purchase completes. If the purchase was successful there will be a
SKPaymentTransaction
and aRCPurchaserInfo
. If the purchase was not successful, there will be anNSError
. If the user cancelled,userCancelled
will beYES
. -
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 currentappUserID
will be aliased together with theappUserID
of the existing user. Going forward, eitherappUserID
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 currentappUserID
will be aliased together with theappUserID
of the existing user. Going forward, eitherappUserID
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 eligibility, 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 givenSKProduct
.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 anNSError
. -
Use this function if you are not using the Offerings system to purchase an
SKProduct
with an appliedSKPaymentDiscount
. 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 withStoreKit
and call theRCPurchaseCompletedBlock
.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 purchasediscount
The
SKPaymentDiscount
to apply to the purchasecompletion
A completion block that is called when the purchase completes. If the purchase was successful there will be a
SKPaymentTransaction
and aRCPurchaserInfo
. If the purchase was not successful, there will be anNSError
. If the user cancelled,userCancelled
will beYES
. -
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 withStoreKit
and call theRCPurchaseCompletedBlock
.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 purchasediscount
The
SKPaymentDiscount
to apply to the purchasecompletion
A completion block that is called when the purchase completes. If the purchase was successful there will be a
SKPaymentTransaction
and aRCPurchaserInfo
. If the purchase was not successful, there will be anNSError
. If the user cancelled,userCancelled
will beYES
. -
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 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
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or nil will delete the subscriber attribute.
-
Subscriber attribute associated with the Airship Channel ID for the user Required for the RevenueCat Airship integration
Declaration
Objective-C
- (void)setAirshipChannelID:(nullable NSString *)airshipChannelID;
Parameters
airshipChannelID
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or 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
Empty String or nil will delete the subscriber attribute.
-
Automatically collect subscriber attributes associated with the device identifiers $idfa, $idfv, $ip
Declaration
Objective-C
- (void)collectDeviceIdentifiers;