BREReceiptManager

Objective-C

@interface BREReceiptManager : NSObject

Swift

class BREReceiptManager : NSObject

This class is the interface to manage e-receipt parsing

Show on GitHub

Properties

  • In order to authenticate Gmail accounts, you must enable the Gmail API in your Google API Console and obtain a Client ID for your app’s bundle. When you have done so, input the Client ID here before attempting to begin the OAuth process for Gmail

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *googleClientId;

    Swift

    var googleClientId: String! { get set }
    Show on GitHub

  • In order to authenticate Outlook accounts, you must register your app at the Azure Portal (https://portal.azure.com/) and add a new App Registration. This will generate an Application (client) ID When you have done so, input that id here before attempting to begin the OAuth process for Outlook

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *outlookClientId;

    Swift

    var outlookClientId: String! { get set }
    Show on GitHub

  • Whether there is a stored provider

    Declaration

    Objective-C

    @property (nonatomic) BOOL userHasProvider;

    Swift

    var userHasProvider: Bool { get set }
    Show on GitHub

  • How far back (in days) to search the user’s inbox for e-receipts

    Default: 14

    Declaration

    Objective-C

    @property (nonatomic) NSInteger dayCutoff;

    Swift

    var dayCutoff: Int { get set }
    Show on GitHub

  • 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

    Declaration

    Objective-C

    @property (nonatomic, strong) NSDate *dateCutoff;

    Swift

    var dateCutoff: Date! { get set }
    Show on GitHub

  • This property works in tandem with dateCutoff and allows you to set the later boundary (i.e. until when) for the search period

    Default: nil

    Declaration

    Objective-C

    @property (nonatomic, strong) NSDate *searchUntilDate;

    Swift

    var searchUntilDate: Date! { get set }
    Show on GitHub

  • If populated, the keys in this dictionary will be used as the senders to search the user’s inbox for, and the corresponding values will be used as the merchant sender address for parsing purposes Default: nil

    Declaration

    Objective-C

    @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *senderWhitelist;

    Swift

    var senderWhitelist: [String : String]! { get set }
    Show on GitHub

  • Controls whether or not to aggregate all emails relating to a given e-receipt order (such as shipping status updates) in the results structure Default: NO

    Declaration

    Objective-C

    @property (nonatomic) BOOL aggregateResults;

    Swift

    var aggregateResults: Bool { get set }
    Show on GitHub

  • If set, overrides the client endpoint configured server side to which results will be POSTed following a remote scrape Default: nil

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *remoteScrapeClientEndpoint;

    Swift

    var remoteScrapeClientEndpoint: String! { get set }
    Show on GitHub

  • If set, overrides the default date cutoff for the current user in remote scrapes Default: nil

    Declaration

    Objective-C

    @property (nonatomic, strong) NSDate *remoteScrapeUserDateCutoff;

    Swift

    var remoteScrapeUserDateCutoff: Date! { get set }
    Show on GitHub

  • If the e-receipts being scraped are known to be from a specific country, set this property to the ISO 2 character country code to improve parsing Deafult: nil

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *countryCode;

    Swift

    var countryCode: String! { get set }
    Show on GitHub

MScience Automated Scrape

  • Permission-delegation gate for automated scraping (off by default). While NO, no automatic background scrape runs even if a task is pending; setting it to YES authorizes the SDK to scrape linked Gmail IMAP accounts on the host’s behalf, while setting it back to NO cancels the pending task. Persist the user’s choice in the host app and apply it at launch after calling enableAutoScrapeWithIdentifier:.

    The background task itself follows the signed-in state: it is scheduled only while an in-scope account is linked — it starts when such an account signs in (if authorized) and is cancelled when the last one signs out — and only one task can ever be pending.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoScrapeEnabled;

    Swift

    var autoScrapeEnabled: Bool { get set }
    Show on GitHub

  • The interval, in hours, at which the automatic background e-receipt scrape runs once enabled via enableAutoScrapeWithIdentifier: — the override for the default 24h refresh. The 12h floor is the only limitation: values below it (including 0 and negatives) fall back to 12 on assignment, anything at or above passes through uncapped, and the getter always reflects the scheduled value. Changing it while enabled reschedules the next run. Default: 24.

    Note: the OS treats the interval as the earliest time the task may run, not a guarantee — the actual cadence depends on system conditions and how often the app is used.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger autoScrapeInterval;

    Swift

    var autoScrapeInterval: Int { get set }
    Show on GitHub

  • A completion handler invoked once per account after each automatic background scrape, delivering the same parameters a manual remote scrape (startRemoteEReceiptScrapeWithCompletion:) reports: the scraped account, its jobId, and any error.

    This block is retained for the life of the SDK singleton and invoked from a background execution context, so capture host objects weakly and don’t touch UIKit from it directly.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) void (^) (NSInteger, BREmailAccount *_Nonnull, NSError *_Nullable) autoScrapeCompletion;

    Swift

    var autoScrapeCompletion: ((Int, BREmailAccount, (any Error)?) -> Void)? { get set }
    Show on GitHub

  • Registers the background app-refresh task under identifier. Each time the OS runs the task the SDK scrapes the linked Gmail IMAP accounts (the initial provider scope) one account at a time and reports each jobId through autoScrapeCompletion.

    Call this once, early in application:didFinishLaunchingWithOptions:, regardless of the user’s opt-in state — BGTaskScheduler requires every launch handler to be registered before the app finishes launching, and only one registration per identifier is permitted per process. Calling it again is a safe no-op. Use autoScrapeEnabled to opt the user in or out at any later time.

    identifier must be UNIQUE to auto-scrape — distinct from every other BGTaskScheduler identifier the app registers (including BRAccountLinkingManager‘s background fetch) — and must be listed under BGTaskSchedulerPermittedIdentifiers in the host Info.plist. A duplicate or missing identifier leaves auto-scrape inactive (the SDK logs and continues rather than crashing the host).

    Declaration

    Objective-C

    - (void)enableAutoScrapeWithIdentifier:(NSString *_Nonnull)identifier;

    Swift

    func enableAutoScrape(withIdentifier identifier: String)

    Parameters

    identifier

    The background-task identifier to register and schedule under.
    Show on GitHub

Class Methods

  • Declaration

    Objective-C

    + (instancetype)shared;

    Swift

    class func shared() -> Self!
    Show on GitHub

Methods

  • Retrieves all the currently linked accounts

    Declaration

    Objective-C

    - (NSArray<BREmailAccount *> *)getLinkedAccounts;

    Swift

    func getLinkedAccounts() -> [BREmailAccount]!
    Show on GitHub

  • Begins the OAuth process for the given provider (currently only Gmail and Outlook supported). If the completion is called with no error, you may then invoke -[BREReceiptManager getEReceiptsWithCompletion:]

    Declaration

    Objective-C

    - (void)beginOAuthForProvider:(BREReceiptProvider)provider
           withViewController:(UIViewController *)viewController
                andCompletion:(void (^)(NSError *))completion;

    Swift

    func beginOAuth(for provider: BREReceiptProvider, with viewController: UIViewController!) async throws

    Parameters

    provider

    The provider you would like to authenticate against
    viewController

    The view controller from which to present the OAuth modal
    completion

    The completion is invoked after the OAuth attempt has completed

    • NSError *error - The error returned during the OAuth attempt, if any. A successful attempt will return nil
    Show on GitHub

  • To connect to Gmail, Yahoo, or AOL accounts via IMAP, the user will have to enable certain account settings. Call this function to start the process

    Declaration

    Objective-C

    - (void)setupIMAPForAccount:(BRIMAPAccount *)account
             viewController:(UIViewController *)viewController
             withCompletion:(void (^)(BRSetupIMAPResult))completion;

    Swift

    func setupIMAP(for account: BRIMAPAccount!, viewController: UIViewController!) async -> BRSetupIMAPResult

    Parameters

    account

    Instantiate an instance of BRIMAPAccount and optionally set custom values for host, port, and TLS
    viewController

    The view controller from which to present the controller that manages the account settings
    completion

    The completion is invoked after the attempt to configure the account has finished

    • BRSetupIMAPResult result - The result of the attempt to configure the account. A successful result is BRSetupIMAPResultEnabledLSA or BRSetupIMAPResultCreatedAppPassword
    Show on GitHub

  • If users have already generated an App Password for a Gmail / Yahoo / AOL IMAP account, use this method to link the account

    Declaration

    Objective-C

    - (void)linkIMAPAccountWithoutSetup:(BRIMAPAccount *)account
                     withCompletion:(void (^)(BRSetupIMAPResult))completion;

    Swift

    func linkIMAPAccountWithoutSetup(_ account: BRIMAPAccount!) async -> BRSetupIMAPResult

    Parameters

    account

    Instantiate an instance of BRIMAPAccount, setting the App Password as the password property
    completion

    The completion is invoked after the attempt to configure the account has finished

    • BRSetupIMAPResult result - The result of the attempt to configure the account. A successful result is BRSetupIMAPResultSaved
    Show on GitHub

  • Verifies that stored IMAP credentials are valid

    Declaration

    Objective-C

    - (void)verifyImapAccount:(BRIMAPAccount *)account
           withCompletion:(void (^)(BOOL, NSError *))completion;

    Swift

    func verifyImapAccount(_ account: BRIMAPAccount!) async throws -> Bool

    Parameters

    account

    The account you would like to verify (must be one of the members of getLinkedAccount
    completion

    The completion is invoked after the attempt to verify IMAP credentials completes

    • BOOL success - indicates whether verification succeeded or not
    • NSError *error - nil on success, otherwise contains error information
    Show on GitHub

  • Attempts to retrieve new (since last check) e-receipts from all linked e-mail accounts. You must have successfully authenticated an OAuth provider, or stored IMAP credentials (and setup IMAP if necessary) prior to calling this method

    Note

    You must have a valid license key set in [BRScanManager sharedManager].licenseKey as well as a valid prod intel key set in [BRScanManager sharedManager].prodIntelKey in order to receive any results

    Declaration

    Objective-C

    - (void)getEReceiptsWithCompletion:(void (^)(NSArray<BRScanResults *> *,
                                             BREmailAccount *,
                                             NSError *))completion;

    Swift

    func eReceipts() async throws -> ([BRScanResults]?, BREmailAccount?)

    Parameters

    completion

    The completion function will be invoked when e-receipt parsing has completed.

    • NSArray<BRScanResults*> *receipts - an array of BRScanResults objects corresponding to the e-receipts that were successfully parsed. You can expect the following order-level properties to be populated:

      • BRScanResults.total
      • BRScanResults.receiptDate
      • BRScanResults.ereceiptOrderNumber

      For products in an e-receipt, you can expect the following properties to be populated:

      • BRProduct.productNumber
      • BRProduct.productDescription
      • BRProduct.unitPrice
      • BRProduct.totalPrice
      • BRProduct.quantity
      • BRProduct.shippingStatus

      If you have product intelligence enabled, we also attempt to populate these product fields:

      • BRProduct.productName
      • BRProduct.brand
      • BRProduct.category
      • BRProduct.size
      • BRProduct.upc
      • BRProduct.imgUrl

    • BREmailAccount *account - the account that the current array of results are for

    • NSError *error - nil on success, otherwise contains the error
    Show on GitHub

  • Same as above method, just for a single linked account

    Declaration

    Objective-C

    - (void)getEReceiptsForAccount:(BREmailAccount *)account
                withCompletion:(void (^)(NSArray<BRScanResults *> *,
                                         BREmailAccount *,
                                         NSError *))completion;

    Swift

    func eReceipts(for account: BREmailAccount!) async throws -> ([BRScanResults]?, BREmailAccount?)
    Show on GitHub

  • Initiates a remote asynchronous scrape for all linked accounts. You must have successfully authenticated an OAuth provider, or stored IMAP credentials (and setup IMAP if necessary) prior to calling this method

    Declaration

    Objective-C

    - (void)startRemoteEReceiptScrapeWithCompletion:
    (void (^)(NSInteger, BREmailAccount *, NSError *))completion;

    Swift

    func startRemoteEReceiptScrape() async throws -> (Int, BREmailAccount?)

    Parameters

    completion

    The completion function will be invoked when the attempt to queue the remote scrape job has completed

    • NSInteger jobId - on success this will contain the job_id which will be used to POST results to your pre-configured results endpoint
    • BREmailAccount *account - on success this will contain the account which the current jobId relates to
    • NSError *error - nil on success, otherwise contains the error
    Show on GitHub

  • Same as above method, just for a single linked account

    Declaration

    Objective-C

    - (void)startRemoteEReceiptScrapeForAccount:(BREmailAccount *)account
                             withCompletion:(void (^)(NSInteger,
                                                      BREmailAccount *,
                                                      NSError *))completion;

    Swift

    func startRemoteEReceiptScrape(for account: BREmailAccount!) async throws -> (Int, BREmailAccount?)
    Show on GitHub

  • Initiates a remote asynchronous scrape of provided email data (for cases where inbox scraping is done outside of the BlinkEReceipt SDK)

    Declaration

    Objective-C

    - (void)startRemoteEReceiptScrapeForEmail:(NSString *)email
                              andProvider:(BREReceiptProvider)provider
                               andEMLFile:(NSString *)emlBase64
                           withCompletion:(void (^)(NSInteger, BREmailAccount *,
                                                    NSError *))completion;

    Swift

    func startRemoteEReceiptScrape(forEmail email: String!, andProvider provider: BREReceiptProvider, andEMLFile emlBase64: String!) async throws -> (Int, BREmailAccount?)

    Parameters

    email

    The email address from which the message was obtained
    provider

    The email provider from which the message was obtained
    emlBase64

    The base 64-encoded EML data
    completion

    The completion function will be invoked when the attempt to queue the remote scrape job has completed

    • NSInteger jobId - on success this will contain the job_id which will be used to POST results to your pre-configured results endpoint
    • BREmailAccount *account - always nil in this context since no account is passed in
    • NSError *error - nil on success, otherwise contains the error
    Show on GitHub

  • For debugging the parsing of e-receipt HTML

    Declaration

    Objective-C

    - (void)parseEReceiptFromSender:(NSString *)senderAddress
                        rawHTML:(NSString *)rawHTML
                     completion:(void (^)(NSArray<BRScanResults *> *,
                                          NSError *))completion;

    Swift

    func parseEReceipt(fromSender senderAddress: String!, rawHTML: String!) async throws -> [BRScanResults]?

    Parameters

    senderAddress

    The email address from which this email originated, must be one of the recognized senders
    rawHTML

    The raw HTML from this email
    completion

    Same as completion for getEReceiptWithCompletion: above
    Show on GitHub

  • Signs out of all linked email accounts and stored e-receipt info. For OAuth providers this signs out of the provider and invalidates the access token. For IMAP providers this removes stored credentails.

    Declaration

    Objective-C

    - (void)signOutWithCompletion:(void (^)(NSError *))completion;

    Swift

    func signOut() async throws

    Parameters

    completion

    The completion function will be invoked when the sign out is complete

    • NSError *error - nil on success, otherwise contains the error
    Show on GitHub

  • Same as above method, just for a single linked account

    Declaration

    Objective-C

    - (void)signOutFromAccount:(BREmailAccount *)account
            withCompletion:(void (^)(NSError *))completion;

    Swift

    func signOut(from account: BREmailAccount!) async throws
    Show on GitHub

  • Resets emails for all linked email accounts so you don’t need to log out and log in during testing

    Declaration

    Objective-C

    - (void)resetEmailsChecked;

    Swift

    func resetEmailsChecked()
    Show on GitHub

  • A passthrough function to be used in your app delegate’s openURL:options:provider: method

    Declaration

    Objective-C

    - (BOOL)openURL:(NSURL *)url
        options:(NSDictionary *)options
       provider:(BREReceiptProvider)provider;

    Swift

    func open(_ url: URL!, options: [AnyHashable : Any]! = [:], provider: BREReceiptProvider) -> Bool
    Show on GitHub