Classes
BRAccountLinkingConfiguration
Configures account linking behavior for the BlinkEReceipt SDK. Inherits from NSObject.
SDK Version: 3.2.0
Properties
dayCutoff
@property (nonatomic) NSInteger dayCutoff;
var dayCutoff: Int { get set }
Set this property to control how far back in the user's history to search for orders.
Default: 15
dateCutoff
@property (nonatomic, strong, nullable) NSDate *dateCutoff;
var dateCutoff: Date? { get set }
This property is an alternative to dayCutoff which allows you to set a specific date/time that serves as the boundary of how far back to search. If set, it will override dayCutoff.
Default: nil
returnLatestOrdersOnly
@property (nonatomic) BOOL returnLatestOrdersOnly;
var returnLatestOrdersOnly: Bool { get set }
Controls historical search depth behavior. When YES (default), subsequent scrapes only retrieve orders back to the previous scrape date. When NO, subsequent scrapes continue fetching historical orders until the cutoff is reached.
Default: YES
countryCode
@property (nonatomic, copy, nonnull) NSString *countryCode;
var countryCode: String { get set }
Set this to a different country to access the correct version of the retailer's site, if it exists for that country (currently only supports Amazon UK).
Default: "US"
BRAccountLinkingConnection
Manages account linking connections to retail merchants. Inherits from NSObject.
SDK Version: 3.2.0
Properties
retailer (read-only)
@property (nonatomic, readonly) BRAccountLinkingRetailer retailer;
var retailer: BRAccountLinkingRetailer { get }
Identifies the linked retail merchant.
username (read-only)
@property (nonatomic, copy, readonly, nullable) NSString *username;
var username: String? { get }
The account username associated with the connection.
lastExecutionTime (read-only)
@property (nonatomic, readonly) NSTimeInterval lastExecutionTime;
var lastExecutionTime: TimeInterval { get }
Timestamp of the most recent execution.
lastExecutionCode (read-only)
@property (nonatomic, readonly) NSUInteger lastExecutionCode;
var lastExecutionCode: UInt { get }
Status code from the last execution attempt.
isAuthenticated (read-only)
@property (nonatomic, readonly) BOOL isAuthenticated;
var isAuthenticated: Bool { get }
It represents the logged in status of the connection. Check this property before calling loginUserForLinkedRetailer.
webviewAuthEnabled
@property (nonatomic) BOOL webviewAuthEnabled;
var webviewAuthEnabled: Bool { get set }
Set this property to YES if you want users to authenticate with merchant's webpage directly.
Default: YES
configuration
@property (nonatomic, strong, nullable) BRAccountLinkingConfiguration *configuration;
var configuration: BRAccountLinkingConfiguration? { get set }
A configuration object that defines the behavior when searching for new orders. See BRAccountLinkingConfiguration.
Initializers
init (Unavailable)
Default initializer is not available. Use one of the designated initializers below.
initWithRetailer:
- (nonnull instancetype)initWithRetailer:(BRAccountLinkingRetailer)retailer;
init(retailer: BRAccountLinkingRetailer)
Parameters:
| Parameter | Description |
|---|---|
retailer | The retailer to link |
initWithRetailer:username:password:
- (nonnull instancetype)initWithRetailer:(BRAccountLinkingRetailer)retailer
username:(NSString * _Nullable)username
password:(NSString * _Nullable)password;
init(retailer: BRAccountLinkingRetailer, username: String?, password: String?)
Parameters:
| Parameter | Description |
|---|---|
retailer | The retailer to link |
username | The account username |
password | The account password |
BRAccountLinkingConnectionIdentifier
An opaque identifier returned when initiating a connection task. Can be used to cancel an in-progress operation. Inherits from NSObject.
SDK Version: 3.2.0
Declaration
@interface BRAccountLinkingConnectionIdentifier : NSObject
@property (nonatomic, copy, readonly, nonnull) NSString *rawValue;
- (instancetype)init NS_UNAVAILABLE;
@end
class BRAccountLinkingConnectionIdentifier : NSObject
Properties
rawValue (read-only)
@property (nonatomic, copy, readonly, nonnull) NSString *rawValue;
var rawValue: String { get }
The raw string value of this identifier.
BRAccountLinkingManager
Manages users' linked retailer accounts for parsing e-receipts. The basic workflow involves capturing user credentials, storing them, grabbing new orders, and retrieving order details. Inherits from NSObject.
SDK Version: 3.2.0
Class Methods
+shared
+ (nonnull instancetype)shared;
class func shared() -> Self
Returns the singleton instance of BRAccountLinkingManager.
Properties
version (read-only)
@property (nonatomic, copy, readonly, nonnull) NSString *version;
var version: String { get }
Returns the current SDK version string.
backgroundFetchCompletion
@property (nonatomic, copy, nullable) void (^)(BRAccountLinkingRetailer,
BRAccountLinkingError, NSString *_Nullable, BRScanResults *_Nullable)
backgroundFetchCompletion;
var backgroundFetchCompletion: ((BRAccountLinkingRetailer,
BRAccountLinkingError, String?, BRScanResults?) -> Void)? { get set }
A completion handler for background operation updates when enabled via enableBackgroundFetchWithIdentifier:. Receives the retailer, an error code, a session ID, and scan results.
Methods
linkAccountWithConnection:withCompletion:
- (BRAccountLinkingConnectionIdentifier *_Nullable)
linkAccountWithConnection:(BRAccountLinkingConnection *_Nonnull)connection
withCompletion:(nonnull void (^)(BRAccountLinkingError,
UIViewController *_Nullable,
NSString *_Nullable))completion;
func linkAccount(with connection: BRAccountLinkingConnection,
withCompletion completion: @escaping (BRAccountLinkingError,
UIViewController?, String?) -> Void) -> BRAccountLinkingConnectionIdentifier?
Links an account for a given retailer.
Parameters:
| Parameter | Description |
|---|---|
connection | A retailer's configuration object |
completion | Callback executed when additional user input is needed or linking completes. Receives an error status, an optional view controller for 2FA/user interaction, and a session ID. |
Returns: A BRAccountLinkingConnectionIdentifier that can be used to cancel the task.
loginUserForLinkedRetailer:withCompletion:
- (BRAccountLinkingConnectionIdentifier *_Nullable)
loginUserForLinkedRetailer:(BRAccountLinkingRetailer)retailer
withCompletion:(nonnull void (^)(BRAccountLinkingError,
UIViewController *_Nullable,
NSString *_Nullable))completion;
func loginUser(forLinkedRetailer retailer: BRAccountLinkingRetailer,
withCompletion completion: @escaping (BRAccountLinkingError,
UIViewController?, String?) -> Void) -> BRAccountLinkingConnectionIdentifier?
Performs a login for the provided retailer. Check isAuthenticated on the connection before calling this method.
Parameters:
| Parameter | Description |
|---|---|
retailer | An ID of a linked retailer |
completion | Callback with error status, an optional view controller, and a session ID |
Returns: A BRAccountLinkingConnectionIdentifier for task cancellation.
getLinkedConnections
- (NSArray<BRAccountLinkingConnection *> *_Nonnull)getLinkedConnections;
func getLinkedConnections() -> [BRAccountLinkingConnection]
Returns a list of connections matching all linked accounts on the device.
Returns: An array of BRAccountLinkingConnection objects.
resetHistoryForConnection:
- (void)resetHistoryForConnection:(BRAccountLinkingConnection *_Nonnull)connection;
func resetHistory(for connection: BRAccountLinkingConnection)
Resets order history for a particular account connection.
Parameters:
| Parameter | Description |
|---|---|
connection | The connection for which to reset order history |
unlinkAccountForRetailer:withCompletion:
- (void)unlinkAccountForRetailer:(BRAccountLinkingRetailer)retailer
withCompletion:(nonnull void (^)(void))completion;
func unlinkAccount(for retailer: BRAccountLinkingRetailer) async
Unlinks a retailer online account.
Parameters:
| Parameter | Description |
|---|---|
retailer | The retailer for which to unlink the account |
completion | Called when async cookie operations complete |
grabNewOrdersForRetailer:withCompletion:
- (BRAccountLinkingConnectionIdentifier *_Nullable)
grabNewOrdersForRetailer:(BRAccountLinkingRetailer)retailer
withCompletion:(nonnull void (^)(BRAccountLinkingRetailer,
BRScanResults *_Nullable,
NSInteger,
UIViewController *_Nullable,
BRAccountLinkingError,
NSString *_Nonnull))completion;
func grabNewOrders(for retailer: BRAccountLinkingRetailer,
withCompletion completion: @escaping (BRAccountLinkingRetailer,
BRScanResults?, Int, UIViewController?, BRAccountLinkingError,
String) -> Void) -> BRAccountLinkingConnectionIdentifier?
Grabs orders for a single retailer only.
Returns: A BRAccountLinkingConnectionIdentifier object.
cancelConnection:
- (void)cancelConnection:(nonnull BRAccountLinkingConnectionIdentifier *)identifier;
func cancelConnection(_ identifier: BRAccountLinkingConnectionIdentifier)
Cancels any connection matching the provided identifier.
Parameters:
| Parameter | Description |
|---|---|
identifier | A BRAccountLinkingConnectionIdentifier object |
updateConnection:
- (void)updateConnection:(BRAccountLinkingConnection *_Nonnull)connection;
func update(_ connection: BRAccountLinkingConnection)
Updates a linked connection with the latest configuration.
Parameters:
| Parameter | Description |
|---|---|
connection | A BRAccountLinkingConnection object |
enableBackgroundFetchWithIdentifier:
- (BRAccountLinkingError)enableBackgroundFetchWithIdentifier:(NSString *_Nonnull)identifier;
func enableBackgroundFetch(withIdentifier identifier: String) -> BRAccountLinkingError
Enables the SDK to check for new orders of all linked retailers periodically in the background, if background fetch is enabled by the host app.
- Tasks run approximately every 1 hour with system-imposed limitations.
- Host apps must enable background fetch in
application(_:didFinishLaunchingWithOptions:). - Calling this method multiple times or after app launch may cause crashes.
- See Apple's
BGAppRefreshTaskdocumentation for setup details.
Parameters:
| Parameter | Description |
|---|---|
identifier | String containing the background task identifier |
Returns: Any BRAccountLinkingError encountered while enabling background fetch.
BRDigitalManager
A singleton manager class for digital receipt operations. Inherits from NSObject.
SDK Version: 3.2.0
Class Methods
+shared
+ (nonnull instancetype)shared;
class func shared() -> Self
Returns the shared singleton instance of BRDigitalManager.
BREReceiptManager
The primary interface for managing e-receipt parsing in the BlinkEReceipt SDK. Handles OAuth authentication, IMAP account setup, and e-receipt extraction from email accounts. Inherits from NSObject.
SDK Version: 3.2.0
Requirements
- A valid license key set in
BRScanManager.licenseKey - A valid product intelligence key set in
BRScanManager.prodIntelKey - For OAuth flows: client IDs configured in
googleClientId/outlookClientId - For IMAP: account credentials or app passwords
Class Methods
+shared
+ (nonnull instancetype)shared;
class func shared() -> Self
Returns the singleton instance of BREReceiptManager.
Properties
googleClientId
@property (nonatomic, copy, nullable) NSString *googleClientId;
var googleClientId: String? { get set }
Required Client ID from the Google API Console for Gmail OAuth authentication.
outlookClientId
@property (nonatomic, copy, nullable) NSString *outlookClientId;
var outlookClientId: String? { get set }
Required Application ID from the Azure Portal for Outlook OAuth authentication.
userHasProvider (read-only)
@property (nonatomic, readonly) BOOL userHasProvider;
var userHasProvider: Bool { get }
Indicates whether a stored email provider exists.
dayCutoff
@property (nonatomic) NSInteger dayCutoff;
var dayCutoff: Int { get set }
Search depth in days.
Default: 14
dateCutoff
@property (nonatomic, strong, nullable) NSDate *dateCutoff;
var dateCutoff: Date? { get set }
Alternative to dayCutoff; sets a specific date boundary for searches.
searchUntilDate
@property (nonatomic, strong, nullable) NSDate *searchUntilDate;
var searchUntilDate: Date? { get set }
Works with dateCutoff to define the search period end date.
senderWhitelist
@property (nonatomic, copy, nullable) NSDictionary *senderWhitelist;
var senderWhitelist: [AnyHashable: Any]? { get set }
Maps sender addresses to merchant identifiers for filtering.
countryCode
@property (nonatomic, copy, nullable) NSString *countryCode;
var countryCode: String? { get set }
ISO 2-character country code to improve parsing accuracy.
aggregateResults
@property (nonatomic) BOOL aggregateResults;
var aggregateResults: Bool { get set }
Controls whether to aggregate related emails (shipping updates, etc.).
Default: NO
remoteScrapeClientEndpoint
@property (nonatomic, copy, nullable) NSString *remoteScrapeClientEndpoint;
var remoteScrapeClientEndpoint: String? { get set }
Override server-configured endpoint for result posting.
remoteScrapeUserDateCutoff
@property (nonatomic, strong, nullable) NSDate *remoteScrapeUserDateCutoff;
var remoteScrapeUserDateCutoff: Date? { get set }
Override the default date cutoff for remote scrapes.
Methods
getLinkedAccounts
- (NSArray<BREmailAccount *> *_Nonnull)getLinkedAccounts;
func getLinkedAccounts() -> [BREmailAccount]
Returns an array of all currently linked BREmailAccount objects.
beginOAuthForProvider:withViewController:andCompletion:
- (void)beginOAuthForProvider:(BREReceiptProvider)provider
withViewController:(UIViewController *_Nonnull)viewController
andCompletion:(nonnull void (^)(BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func beginOAuth(for provider: BREReceiptProvider,
with viewController: UIViewController,
andCompletion completion: @escaping (BREmailAccount?, Error?) -> Void)
Initiates the OAuth flow for Gmail or Outlook. See BREReceiptProvider.
setupIMAPForAccount:viewController:withCompletion:
- (void)setupIMAPForAccount:(BRIMAPAccount *_Nonnull)account
viewController:(UIViewController *_Nonnull)viewController
withCompletion:(nonnull void (^)(BRSetupIMAPResult,
BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func setupIMAP(for account: BRIMAPAccount,
viewController: UIViewController,
withCompletion completion: @escaping (BRSetupIMAPResult,
BREmailAccount?, Error?) -> Void)
Guides IMAP setup for Gmail, Yahoo, or AOL accounts. Returns a BRSetupIMAPResult.
linkIMAPAccountWithoutSetup:withCompletion:
- (void)linkIMAPAccountWithoutSetup:(BRIMAPAccount *_Nonnull)account
withCompletion:(nonnull void (^)(BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func linkIMAPAccountWithoutSetup(_ account: BRIMAPAccount,
withCompletion completion: @escaping (BREmailAccount?, Error?) -> Void)
Links an account when an App Password has already been generated.
verifyImapAccount:withCompletion:
- (void)verifyImapAccount:(BRIMAPAccount *_Nonnull)account
withCompletion:(nonnull void (^)(BOOL, NSError *_Nullable))completion;
func verifyImapAccount(_ account: BRIMAPAccount,
withCompletion completion: @escaping (Bool, Error?) -> Void)
Validates stored IMAP credentials.
getEReceiptsWithCompletion:
- (void)getEReceiptsWithCompletion:(nonnull void (^)(NSArray<BRScanResults *> *_Nullable,
BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func getEReceipts(withCompletion completion: @escaping ([BRScanResults]?,
BREmailAccount?, Error?) -> Void)
Retrieves e-receipts from all linked accounts.
Expected result fields:
- Order level:
total,receiptDate,ereceiptOrderNumber - Products:
productNumber,productDescription,unitPrice,totalPrice,quantity,shippingStatus - With product intelligence:
productName,brand,category,size,upc,imgUrl
getEReceiptsForAccount:withCompletion:
- (void)getEReceiptsForAccount:(BREmailAccount *_Nonnull)account
withCompletion:(nonnull void (^)(NSArray<BRScanResults *> *_Nullable,
BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func getEReceipts(for account: BREmailAccount,
withCompletion completion: @escaping ([BRScanResults]?,
BREmailAccount?, Error?) -> Void)
Retrieves e-receipts from a single linked account.
startRemoteEReceiptScrapeWithCompletion:
- (void)startRemoteEReceiptScrapeWithCompletion:(nonnull void (^)(NSInteger,
BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func startRemoteEReceiptScrape(withCompletion completion: @escaping (Int,
BREmailAccount?, Error?) -> Void)
Queues a remote scrape job for all linked accounts. Completion receives a job ID, the email account, and any error.
startRemoteEReceiptScrapeForAccount:withCompletion:
- (void)startRemoteEReceiptScrapeForAccount:(BREmailAccount *_Nonnull)account
withCompletion:(nonnull void (^)(NSInteger,
BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func startRemoteEReceiptScrape(for account: BREmailAccount,
withCompletion completion: @escaping (Int, BREmailAccount?, Error?) -> Void)
Queues a remote scrape job for a single account.
startRemoteEReceiptScrapeForEmail:andProvider:andEMLFile:withCompletion:
- (void)startRemoteEReceiptScrapeForEmail:(NSString *_Nonnull)email
andProvider:(BREReceiptProvider)provider
andEMLFile:(NSData *_Nonnull)emlFile
withCompletion:(nonnull void (^)(NSInteger,
BREmailAccount *_Nullable,
NSError *_Nullable))completion;
func startRemoteEReceiptScrape(forEmail email: String,
andProvider provider: BREReceiptProvider,
andEMLFile emlFile: Data,
withCompletion completion: @escaping (Int, BREmailAccount?, Error?) -> Void)
Processes external EML data via remote scrape.
parseEReceiptFromSender:rawHTML:completion:
- (void)parseEReceiptFromSender:(NSString *_Nonnull)sender
rawHTML:(NSString *_Nonnull)html
completion:(nonnull void (^)(BRScanResults *_Nullable,
NSError *_Nullable))completion;
func parseEReceipt(fromSender sender: String, rawHTML html: String,
completion: @escaping (BRScanResults?, Error?) -> Void)
Directly parses raw HTML for testing purposes.
signOutWithCompletion:
- (void)signOutWithCompletion:(nonnull void (^)(NSError *_Nullable))completion;
func signOut(withCompletion completion: @escaping (Error?) -> Void)
Logs out all accounts; invalidates OAuth tokens and removes IMAP credentials.
signOutFromAccount:withCompletion:
- (void)signOutFromAccount:(BREmailAccount *_Nonnull)account
withCompletion:(nonnull void (^)(NSError *_Nullable))completion;
func signOut(from account: BREmailAccount,
withCompletion completion: @escaping (Error?) -> Void)
Logs out a single account.
resetEmailsChecked
- (void)resetEmailsChecked;
func resetEmailsChecked()
Clears email check history for testing without re-authentication.
openURL:options:provider:
- (BOOL)openURL:(NSURL *_Nonnull)url
options:(NSDictionary *_Nonnull)options
provider:(BREReceiptProvider)provider;
func open(_ url: URL, options: [UIApplication.OpenURLOptionsKey: Any],
provider: BREReceiptProvider) -> Bool
App delegate passthrough for OAuth callback handling. Call this from application(_:open:options:).
BREmailAccount
Represents a user email account. Inherits from NSObject.
SDK Version: 3.2.0
Properties
provider (read-only)
@property (nonatomic, readonly) BREReceiptProvider provider;
var provider: BREReceiptProvider { get }
The provider for this account. See BREReceiptProvider.
email (read-only)
@property (nonatomic, strong, readonly, nonnull) NSString *email;
var email: String { get }
The email address for this account.
isAuthenticated (read-only)
@property (nonatomic, readonly) BOOL isAuthenticated;
var isAuthenticated: Bool { get }
It represents the logged in status of the account.
BRIMAPAccount
Represents an IMAP account. Should be instantiated with the user's credentials prior to beginning IMAP setup in BREReceiptManager. Inherits from BREmailAccount.
SDK Version: 3.2.0
Properties
webviewAuthEnabled
@property (nonatomic) BOOL webviewAuthEnabled;
var webviewAuthEnabled: Bool { get set }
Set this property to YES if you want users to provide input for each step from the authentication process directly in a webview.
Only affects the BREReceiptProviderGmailIMAP provider.
Default: NO
Methods
initWithGmailIMAP
- (nonnull instancetype)initWithGmailIMAP;
init(gmailIMAP: ())
Use this method to set up the Gmail IMAP provider directly.
initWithProvider:email:password:
- (nonnull instancetype)initWithProvider:(BREReceiptProvider)provider
email:(nonnull NSString *)email
password:(nonnull NSString *)password;
init(provider: BREReceiptProvider, email: String, password: String)
The first step in linking a user's IMAP account. Instantiate this class with the user's credentials.
Parameters:
| Parameter | Description |
|---|---|
provider | The provider for this IMAP account |
email | The email address for this IMAP account |
password | The user's regular password — an "app password" will be created automatically during setup |
configureCustomHost:port:useTLS:
- (void)configureCustomHost:(nonnull NSString *)host
port:(NSInteger)port
useTLS:(BOOL)useTLS;
func configureCustomHost(_ host: String, port: Int, useTLS: Bool)
If the IMAP provider is not Gmail, AOL, or Yahoo, use this method to specify the provider's configuration.
Parameters:
| Parameter | Description |
|---|---|
host | The provider's IMAP host name |
port | The provider's IMAP port |
useTLS | Whether the provider uses TLS (virtually all providers do) |