Button Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | Button.h |
Shared Button Intance
+ sharedButton
Returns the singleton shared Button instance
+ (nonnull Button *)sharedButtonReturn Value
Button object singleton
Discussion
Returns the singleton shared Button instance
Note: Returns nil on iOS7 and older platform versions *
Declared In
Button.h
Configuration
– configureWithApplicationId:completion:
Configures a Button instance with the provided applicationId
- (void)configureWithApplicationId:(nonnull NSString *)applicationId completion:(nullable void ( ^ ) ( NSError *__nullable error ))completionHandlerParameters
applicationId |
Your applicationId (required) |
|---|---|
completionHandler |
A block to be executed upon completion (optional). * |
Discussion
Configures a Button instance with the provided applicationId
Declared In
Button.h
– configureWithApplicationId:userId:completion:
Configures a Button instance with the provided applicationId
- (void)configureWithApplicationId:(nonnull NSString *)applicationId userId:(nullable NSString *)userId completion:(nullable void ( ^ ) ( NSError *__nullable error , NSURL *__nullable targetURL ))completionHandlerParameters
applicationId |
Your applicationId (required) |
|---|---|
userId |
The user identifier (if known) for the current user to associate with the Button session (optional). |
completionHandler |
A block to be executed upon completion (optional). |
Discussion
Configures a Button instance with the provided applicationId
Note: If you do not have the Id of your logged in user when you call this method (typically in -application:didFinishLaunchingWithOptions:),
make sure you call setUserIdentifier: once you’ve successfully acquired the Id for your logged in user.
The completion handler takes two parameters - error Will be set in the event of a configuration error. - targetURL If not nil, a URL that specifies the user’s expected destination in your app. *
Declared In
Button.h
User Identifier
– setUserIdentifier:
Associate your ID for the current user with the Button session.
- (void)setUserIdentifier:(nonnull NSString *)userIdentifierParameters
userIdentifier |
your identifier for the user. |
|---|
Discussion
Associate your ID for the current user with the Button session.
Note: This is required for attribution.
To correctly configure Button for attribution, make sure to:
1. Pass your logged in user’s Id when configuring Button (use configureWithApplicationId:userId:completion:).
2. Call this method with your user’s id after a user successfully logs into your app.
If you don’t have the Id of your logged in user in at the time you call configureWithApplicationId:userId:completion:
(typically in -application:didFinishLaunchingWithOptions:), make sure you call this method once you’ve successfully
acquired the Id for your logged in user.
Note that passing nil here is a noop and will not remove the user Id from the session.
If your user is logging out, call logOut to reset the session and user data in Button.
*
Declared In
Button.h
Button Actions
– fetchAppActionWithButtonId:context:publisherReference:completion:
Fetches an app action for a buttonId and contextually relevant data.
- (void)fetchAppActionWithButtonId:(nonnull NSString *)buttonId context:(nonnull BTNContext *)context publisherReference:(nullable NSString *)publisherReference completion:(nonnull void ( ^ ) ( BTNAppAction *__nullable appAction , NSError *__nullable error ))completionHandlerParameters
buttonId |
The identifier for a button (e.g. btn-xxxxxxxxxxxx). |
|---|---|
context |
A BTNContext object providing context about your user’s current activity. |
publisherReference |
A token to be associated with all downstream orders, transactions and webhooks. (Max 100 chars.) |
completionHandler |
A block to be executed upon completion. |
Discussion
Fetches an app action for a buttonId and contextually relevant data.
The completion handler takes two parameters - appAction A BTNAppAction instance or nil if no action was found for the provided context. - error An error will be present if a network or server error occurred.
Note: You should not cache app actions yourself. App actions are automatically cached for as long as their data is valid.
For example, calling this method again with the same buttonId and context will return a previously fetched
and cached app action if the action is still valid.
Declared In
Button.h
– fetchAppActionWithButtonId:context:completion:
- (void)fetchAppActionWithButtonId:(nonnull NSString *)buttonId context:(nonnull BTNContext *)context completion:(nonnull void ( ^ ) ( BTNAppAction *__nullable appAction , NSError *__nullable error ))completionHandlerDeclared In
Button.h
– willDisplayButtonWithId:context:completion:
Checks whether Button has an action available for a buttonId and contextually relevant data.
- (void)willDisplayButtonWithId:(nonnull NSString *)buttonId context:(nonnull BTNContext *)context completion:(nonnull void ( ^ ) ( BOOL willDisplay ))completionHandlerParameters
buttonId |
The identifier for a button (e.g. btn-xxxxxxxxxxxx). |
|---|---|
context |
A BTNContext object providing context about your user’s current activity. |
completionHandler |
A block to be executed upon completion. |
Discussion
Checks whether Button has an action available for a buttonId and contextually relevant data.
Declared In
Button.h
Purchase Path
– fetchAppActionWithURL:publisherReference:completion:
Fetches an app action for a supported url.
- (void)fetchAppActionWithURL:(nonnull NSURL *)url publisherReference:(nullable NSString *)publisherReference completion:(nonnull void ( ^ ) ( BTNAppAction *__nullable appAction , NSError *__nullable error ))completionHandlerParameters
url |
A merchant or affilate url. |
|---|---|
publisherReference |
A token to be associated with all downstream orders, transactions and webhooks. (Max 100 chars.) |
completionHandler |
A block to be executed upon completion. |
Discussion
Fetches an app action for a supported url.
The completion handler takes two parameters - appAction A BTNAppAction instance or nil if no action was found for the provided url. - error An error will be present if an error occurred.
Note: Returned actions are NOT cached.
Note: Returns immidiately if provided url is not supported.
Declared In
Button.h
– fetchAppActionWithURL:completion:
- (void)fetchAppActionWithURL:(nonnull NSURL *)url completion:(nonnull void ( ^ ) ( BTNAppAction *__nullable appAction , NSError *__nullable error ))completionHandlerDeclared In
Button.h
– canFetchAppActionWithURL:
Checks if app action can be fetched for provided url.
- (BOOL)canFetchAppActionWithURL:(nonnull NSURL *)urlParameters
url |
A merchant or affilate url. return BOOL indicating whether the Button SDK can fetch app action for provided url. |
|---|
Discussion
Checks if app action can be fetched for provided url.
Can be used with - fetchAppActionWithURL:completion:
@code
if ([[Button sharedButton] canFetchAppActionWithURL:url]) {
[[Button sharedButton] fetchAppActionWithURL:url completion:^(BTNAppAction appAction, NSError error) {
if (appAction) {
[appAction invokeAction];
}
}];
}
@endcode
Declared In
Button.h
– fetchAppActionWithMerchantId:publisherReference:completion:
Fetches an app action for a merchantId.
- (void)fetchAppActionWithMerchantId:(nonnull NSString *)merchantId publisherReference:(nullable NSString *)publisherReference completion:(nonnull void ( ^ ) ( BTNAppAction *__nullable appAction , NSError *__nullable error ))completionHandlerParameters
merchantId |
The identifier for a merchant (e.g. org-xxxxxxxxxxxx). |
|---|---|
publisherReference |
A token to be associated with all downstream orders, transactions and webhooks. (Max 100 chars.) |
completionHandler |
A block to be executed upon completion. |
Discussion
Fetches an app action for a merchantId.
The completion handler takes two parameters - appAction A BTNAppAction instance or nil if no action was found for the provided merchantId. - error An error will be present if a network or server error occurred.
Note: Returned actions are NOT cached.
Declared In
Button.h
– fetchAppActionWithMerchantId:completion:
- (void)fetchAppActionWithMerchantId:(nonnull NSString *)merchantId completion:(nonnull void ( ^ ) ( BTNAppAction *__nullable appAction , NSError *__nullable error ))completionHandlerDeclared In
Button.h
– presentMerchantAction:
Pass your URL to Button via BTNMerchantAction.
- (void)presentMerchantAction:(nonnull BTNMerchantAction *)merchantActionParameters
merchantAction |
The merchant link url and additional associated data. |
|---|
Discussion
Pass your URL to Button via BTNMerchantAction.
When starting a BTNMerchantAction, Button will take control and detect whether the URL can be exchanged for a commissioned Checkout Flow including installing the merchant app if necessary. If Button cannot exchange the URL, it will open it in an in-app web view.
Declared In
Button.h
– presentMerchantAction:completion:
Similar to presentMerchantAction: Includes a callback to know when the Button Checkout Flow has completed.
- (void)presentMerchantAction:(nonnull BTNMerchantAction *)merchantAction completion:(nonnull void ( ^ ) ( BTNMerchantActionResult result , NSError *__nullable error ))completionHandlerParameters
merchantAction |
The merchant link url and additional associated data. |
|---|---|
completionHandler |
A block to be executed upon completion. |
Discussion
Similar to presentMerchantAction: Includes a callback to know when the Button Checkout Flow has completed.
The completion handler takes two parameters - result Result code of presentation. - error An error will be present if an error occurred.
Declared In
Button.h
– presentMerchantAction:settings:completion:
Similar to presentMerchantAction: Includes a BTNMerchantActionSettings to configure whether Button should handle URLs that it cannot commission.
- (void)presentMerchantAction:(nonnull BTNMerchantAction *)merchantAction settings:(nonnull BTNMerchantActionSettings *)settings completion:(nonnull void ( ^ ) ( BTNMerchantActionResult result , NSError *__nullable error ))completionHandlerParameters
merchantAction |
The merchant link url and additional associated data. |
|---|---|
settings |
Merchant Action presentation settings. |
completionHandler |
A block to be executed upon completion. |
Discussion
Similar to presentMerchantAction: Includes a BTNMerchantActionSettings to configure whether Button should handle URLs that it cannot commission.
The completion handler takes two parameters - result Result code of presentation. - error An error will be present if an error occurred.
Declared In
Button.h
Checkout Extension
– setCheckoutExtension:
Sets a checkout extension to be used during the In-App Checkout experience. @important The passed object will be strongly held by Button.
- (void)setCheckoutExtension:(nullable id<BTNCheckoutExtension>)checkoutExtensionParameters
checkoutExtension |
your object conforming to the CheckoutExtension protocol. |
|---|
Discussion
Sets a checkout extension to be used during the In-App Checkout experience. @important The passed object will be strongly held by Button.
Declared In
Button.h
Reporting Custom Events
– reportEventWithName:properties:
Report an event to Button.
- (void)reportEventWithName:(nonnull NSString *)eventName properties:(nullable NSDictionary<NSString*,NSString*> *)propertiesParameters
eventName |
The name of the event. |
|---|---|
properties |
A dictionary of key-value string pairs for adding detail to the event. |
Discussion
Report an event to Button.
Declared In
Button.h
Deep Link Handling
– continueUserActivity:
Continues incoming NSUserActivity objects from Universal Links (e.g. Button Links). This method should be called from your application delegate method: @c
- (BOOL)continueUserActivity:(nonnull NSUserActivity *)userActivityReturn Value
BOOL indicating whether the Button SDK can & will handle the userActivity. *
Discussion
Continues incoming NSUserActivity objects from Universal Links (e.g. Button Links). This method should be called from your application delegate method: @c
-application:continueUserActivity:userActivity:restorationHandler:
Declared In
Button.h
– handleURL:
Handles an incoming URL to your App. This method should be called from your Application Delegate method: @c
- (BOOL)handleURL:(nonnull NSURL *)urlReturn Value
BOOL indicating whether the Button SDK can & will handle the URL. *
Discussion
Handles an incoming URL to your App. This method should be called from your Application Delegate method: @c
-application:openURL:sourceApplication:annotation:
Declared In
Button.h
Attribution
– referrerToken
Returns the current referrerToken for the last inbound link from the Button marketplace or nil if none is present.
- (nullable NSString *)referrerTokenReturn Value
String value of the last inbound referrerToken *
Discussion
Returns the current referrerToken for the last inbound link from the Button marketplace or nil if none is present.
Declared In
Button.h
Log Out
– logOut
Discards the current session, discards any user unique data, and creates a new session. *
- (void)logOutDiscussion
Discards the current session, discards any user unique data, and creates a new session. *
Declared In
Button.h
Debug Logging
– setDebugLoggingEnabled:
Sets whether the Button SDK will output debug log messages to the console.
- (void)setDebugLoggingEnabled:(BOOL)enabledParameters
enabled |
Pass YES to enable debug log messages to the console. |
|---|
Discussion
Sets whether the Button SDK will output debug log messages to the console.
You should ship to the App Store with this disabled.
Note: The default value is NO.
Declared In
Button.h
Permissions
+ allowButtonToRequestLocationPermission:
@important This functionality has been removed as of 5.30.0 (deprecated in 5.16.0). If you relied on Button to request location permission for your app, you can replace the functionality following [Apple’s documentation) (https://developer.apple.com/documentation/corelocation/choosing_the_authorization_level_for_location_services/requesting_when_in_use_authorization)
+ (void)allowButtonToRequestLocationPermission:(BOOL)isAllowedParameters
isAllowed |
this parameter is ignored as of 5.30.0. |
|---|
Discussion
@important This functionality has been removed as of 5.30.0 (deprecated in 5.16.0). If you relied on Button to request location permission for your app, you can replace the functionality following [Apple’s documentation) (https://developer.apple.com/documentation/corelocation/choosing_the_authorization_level_for_location_services/requesting_when_in_use_authorization)
Declared In
Button.h
Developer Setup
+ setDeveloperBuildReportingEnabled:
Reports associated domain configuration when your build is developer signed ONLY (enabled by default).
+ (void)setDeveloperBuildReportingEnabled:(BOOL)enabledParameters
enabled |
Pass NO to disable developer build reporting. |
|---|
Discussion
Reports associated domain configuration when your build is developer signed ONLY (enabled by default).
Note: This should be enabled when you’re setting up the SDK to make sure your bttn.io domains are
set up correctly in the Button Dashboard. If you have a large binary, you can pass NO to disable this
feature after you’ve confirmed your bttn.io universal links are properly configured.
Declared In
Button.h
Automatic Attribution
+ setAutomaticAttributionEnabled:
Incoming URLs are automatically routed to Button for attribution by default.
+ (void)setAutomaticAttributionEnabled:(BOOL)enabledDiscussion
Incoming URLs are automatically routed to Button for attribution by default.
Note: It is highly recommended that you leave this feature enabled.
If you prefer to follow the manual integration steps to route incoming URLs to Button for attribution, you can disable this feature by overriding +load in you app delegate: @code + (void)load { [Button setAutomaticAttributionEnabled:NO]; } @endcode
Declared In
Button.h
Version
+ sdkVersion
Version of the Button SDK *
+ (nonnull NSString *)sdkVersionDiscussion
Version of the Button SDK *
Declared In
Button.h