Skip to main content

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:

ParameterDescription
retailerThe 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:

ParameterDescription
retailerThe retailer to link
usernameThe account username
passwordThe 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:

ParameterDescription
connectionA retailer's configuration object
completionCallback 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:

ParameterDescription
retailerAn ID of a linked retailer
completionCallback 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:

ParameterDescription
connectionThe 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:

ParameterDescription
retailerThe retailer for which to unlink the account
completionCalled 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:

ParameterDescription
identifierA BRAccountLinkingConnectionIdentifier object

updateConnection:

- (void)updateConnection:(BRAccountLinkingConnection *_Nonnull)connection;
func update(_ connection: BRAccountLinkingConnection)

Updates a linked connection with the latest configuration.

Parameters:

ParameterDescription
connectionA 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.

note
  • 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 BGAppRefreshTask documentation for setup details.

Parameters:

ParameterDescription
identifierString 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.

note

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:

ParameterDescription
providerThe provider for this IMAP account
emailThe email address for this IMAP account
passwordThe 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:

ParameterDescription
hostThe provider's IMAP host name
portThe provider's IMAP port
useTLSWhether the provider uses TLS (virtually all providers do)