Auto-Scrape

The automated e-receipt scrape is a host-controlled permission gate plus a periodic background scrape of the user's linked Gmail IMAP accounts. Once the host registers the background task and opts the user in, the system periodically runs the same remote scrape as startRemoteEReceiptScrapeWithCompletion: over every eligible linked account and reports each account's jobId through a completion block.

The background task follows the signed-in state: it is scheduled only while an eligible Gmail account is linked — it starts when such an account signs in (with the gate on) and is cancelled when the last one signs out — and only one task request can ever be pending.

The gate is off by default and is not persisted by the SDK — persist the user's choice in your app and re-apply it at launch, after calling enableAutoScrapeWithIdentifier:.

Auto-scrape is exposed on the BREReceiptManager singleton.

Declaration

@interface BREReceiptManager : NSObject

class BREReceiptManager : NSObject

---

Quick Reference

Properties

Property	Description
autoScrapeEnabled	The permission gate; authorizes or cancels the background scrape
autoScrapeInterval	The scrape cadence in hours (minimum 12, default 24, no upper cap)
autoScrapeCompletion	Per-account completion block — the account, its jobId, and any error

Methods

Method	Description
enableAutoScrapeWithIdentifier:	Registers the background app-refresh task

---

Properties

autoScrapeEnabled

@property (nonatomic) BOOL autoScrapeEnabled;

var autoScrapeEnabled: Bool { get set }

The permission gate. 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; setting it back to NO cancels the pending task. Off by default. Persist the user's choice in the host app and apply it at launch, after calling enableAutoScrapeWithIdentifier:.

The task itself is scheduled only while an eligible account is linked: it starts when such an account signs in (with the gate on) and is cancelled when the last one signs out, so the task never keeps running for a signed-out user.

---

autoScrapeInterval

@property (nonatomic) NSInteger autoScrapeInterval;

var autoScrapeInterval: Int { get set }

The interval, in hours, at which the automatic background scrape runs once enabled — the override for the default 24 hour refresh. The 12 hour minimum is the only limitation: values below it (including zero 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.

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.

---

autoScrapeCompletion

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

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

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.

---

Methods

enableAutoScrapeWithIdentifier:

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

func enableAutoScrape(withIdentifier identifier: String)

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.

Parameters

Parameter	Description
identifier	The background-task identifier to register and schedule under.

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).

---

Provider Scope

Automated scrapes currently cover Gmail IMAP accounts only (the initial provider scope). Other linked providers are skipped by the background scrape; the manual scrape paths are unaffected.

---

Requirements

• Register the task identifier with enableAutoScrapeWithIdentifier: before application:didFinishLaunchingWithOptions: returns, and list the same identifier under BGTaskSchedulerPermittedIdentifiers in your Info.plist.
• Enable the app's Background Modes (background fetch / processing) so the OS can run the task.
• The schedule is tied to the linked accounts: the task is pending only while at least one eligible Gmail account is linked. It starts when such an account signs in (with the gate on) and is cancelled when the last one signs out.
• Set the completion at launch too: assign autoScrapeCompletion in application:didFinishLaunchingWithOptions:. Background launches run the scrape whether or not the block is set, and job reports delivered while it is unset are dropped.
• Timing is best-effort: earliestBeginDate is a floor, not a schedule. The OS decides when — and whether — to run based on app usage, battery, and the user's Background App Refresh setting, and it never launches background tasks for an app the user has force-quit until it is opened again.
• Runs are budgeted (~30 seconds): the SDK queues one lightweight remote job per account, and a run cut off by expiration picks up on the next cycle.
• Treat the completion as telemetry: each job's results are delivered server-side to the configured client endpoint, so a missed in-app report never loses data — rely on your backend as the source of truth.

Note: the gate is not persisted by the SDK. Store the user's opt-in in your app and re-apply it at launch (via autoScrapeEnabled) after registering the task.