Classes

BlinkEngageSDK

The main SDK singleton. Configure it once in application(_:didFinishLaunchingWithOptions:) and access it via BlinkEngageSDK.shared everywhere else.

Declaration

@interface BlinkEngageSDK : NSObject

class BlinkEngageSDK : NSObject

Type Methods

`start(debugMode:)`

+ (void)startWithDebugMode:(BOOL)debugMode;

static func start(debugMode: Bool)

Configures Google Mobile Ads and constructs the SDK singleton. Must be called exactly once, on the main thread, before any BRScanManager.shared() calls — typically as the first statement in application(_:didFinishLaunchingWithOptions:).

Pass true for development and internal testing builds: the device is registered as a GAM test device so real ads are served safely without affecting production metrics. Pass false for App Store submissions and customer-facing builds.

Calling more than once or from a background thread triggers a precondition failure.

Type Properties

`shared` (read-only)

@property (class, nonatomic, readonly) BlinkEngageSDK *shared;

static var shared: BlinkEngageSDK { get }

The shared SDK instance. Valid only after start(debugMode:) has been called — accessing it before that triggers a precondition failure.

Instance Properties

`user` (read-only)

@property (nonatomic, readonly) BlinkEngageUser *user;

let user: BlinkEngageUser

The user identity object. Set emailHash, phoneHash, and clientUserId on this object to register the user with the backend. Setting either hash automatically triggers registration — no explicit call required. See BlinkEngageUser.

`rewardConfig`

@property (nonatomic) BlinkEngageRewardConfig *rewardConfig;

var rewardConfig: BlinkEngageRewardConfig

The reward display and callback configuration. Assign a configured BlinkEngageRewardConfig before presenting any SDK UI. Currency styling is applied when SDK views load — changes after a view is on screen do not take effect until the view is recreated.

Default: BlinkEngageRewardConfig with all defaults and a no-op rewardCallback.

See BlinkEngageRewardConfig and Reward Currency.

`appearance`

@property (nonatomic) Appearance *appearance;

@MainActor var appearance: Appearance

The theme container. Assign an Appearance instance before presenting any SDK UI. Must be set on the main thread.

Default: Appearance() — all SDK defaults, no custom theme.

See Appearance and Theming Guide.

`eventCallback`

@property (nonatomic, copy, nullable) void (^eventCallback)(NSString * _Nonnull eventName, NSDictionary<NSString *, id> * _Nullable metadata);

var eventCallback: ((_ eventName: String, _ metadata: [String: Any]?) -> Void)?

An optional closure called when SDK events occur. Assign once at app launch to receive events for the lifetime of the app session. For events that carry metadata (offer_detail_viewed, offer_clipped), metadata includes the offer title under the BlinkEngageSDK.eventMetadataOfferTitle key. For all other events, metadata is nil.

Default: nil

Event Name Constants

String constants for the eventName parameter of eventCallback.

`eventScanSessionStarted`

@property (class, nonatomic, readonly) NSString *eventScanSessionStarted;

static let eventScanSessionStarted: String

A BlinkReceipt scan session has begun.

Value: "scan_session_started"

`eventAdLoadingStarted`

@property (class, nonatomic, readonly) NSString *eventAdLoadingStarted;

static let eventAdLoadingStarted: String

The ad loading screen is displayed.

Value: "ad_loading_started"

`eventPostScanViewed`

@property (class, nonatomic, readonly) NSString *eventPostScanViewed;

static let eventPostScanViewed: String

The post-scan receipt summary screen is displayed.

Value: "post_scan_viewed"

`eventOfferWallViewed`

@property (class, nonatomic, readonly) NSString *eventOfferWallViewed;

static let eventOfferWallViewed: String

The all-offers wall (.all type) is displayed. Fires at most once per app session.

Value: "offer_wall_viewed"

`eventOfferDetailViewed`

@property (class, nonatomic, readonly) NSString *eventOfferDetailViewed;

static let eventOfferDetailViewed: String

An offer detail screen is opened. Fires at most once per unique offer per app session. metadata[BlinkEngageSDK.eventMetadataOfferTitle] contains the offer title.

Value: "offer_detail_viewed"

`eventOfferClipped`

@property (class, nonatomic, readonly) NSString *eventOfferClipped;

static let eventOfferClipped: String

The user clips an offer. metadata[BlinkEngageSDK.eventMetadataOfferTitle] contains the offer title.

Value: "offer_clipped"

Event Metadata Keys

`eventMetadataOfferTitle`

@property (class, nonatomic, readonly) NSString *eventMetadataOfferTitle;

static let eventMetadataOfferTitle: String

Key for the offer title string in the metadata dictionary. Present for eventOfferDetailViewed and eventOfferClipped; absent for all other events.

Value: "offer_title"

BlinkEngageUser

Holds the identity of the current user. The SDK automatically registers the user with the backend whenever either hash property is set to a non-nil value.

Access via BlinkEngageSDK.shared.user — do not instantiate directly.

Declaration

@interface BlinkEngageUser : NSObject

class BlinkEngageUser : NSObject

Properties

`emailHash`

@property (nonatomic, copy, nullable) NSString *emailHash;

var emailHash: String?

SHA-256 hash of the user's email address. Setting this (alone or with phoneHash) triggers automatic user registration. Set to nil on logout.

Default: nil

`phoneHash`

@property (nonatomic, copy, nullable) NSString *phoneHash;

var phoneHash: String?

SHA-256 hash of the user's phone number. Setting this (alone or with emailHash) triggers automatic user registration. Set to nil on logout.

Default: nil

`clientUserId`

@property (nonatomic, copy, nullable) NSString *clientUserId;

var clientUserId: String?

Your app's internal user identifier. Optional — use it to correlate BlinkEngage activity with your own user records. Does not trigger registration on its own; set at least one hash first.

Default: nil

BlinkEngageRewardConfig

Immutable value type that configures how rewards are calculated, displayed, and communicated back to the host app. Create one instance and assign it to BlinkEngageSDK.shared.rewardConfig.

Declaration

@interface BlinkEngageRewardConfig : NSObject

final class BlinkEngageRewardConfig : NSObject

Initializers

`init(rewardCallback:)` (Swift)

init(
    currencyName: String = "points",
    currencyCode: String? = nil,
    currencyCodePosition: RewardCurrencyCodePosition = .leading,
    currencyPerDollar: Double = 100.0,
    userPayoutPercentage: Double = 0.6,
    currencyImage: UIImage? = nil,
    currencyImageLocations: RewardCurrencyImageLocations = .all,
    rewardCurrencyLabelStyle: RewardCurrencyLabelStyle = .currencyImage,
    rewardCurrencyMessagingTextStyle: RewardCurrencyMessagingTextStyle = .currencyName,
    rewardRounding: RewardCurrencyRounding = .whole,
    rewardCallback: @escaping (_ context: String, _ rewardAmount: NSNumber?, _ blinkReceiptId: String?) -> NSNumber?
)

All parameters have defaults except rewardCallback, which is required.

Obj-C Initializer

- (instancetype)initWithCurrencyName:(NSString *)currencyName
                        currencyCode:(NSString * _Nullable)currencyCode
                currencyCodePosition:(RewardCurrencyCodePosition)currencyCodePosition
                   currencyPerDollar:(double)currencyPerDollar
               userPayoutPercentage:(double)userPayoutPercentage
                       currencyImage:(UIImage * _Nullable)currencyImage
               currencyImageLocations:(NSInteger)currencyImageLocations
                    rewardLabelStyle:(RewardCurrencyLabelStyle)rewardLabelStyle
                messagingTextStyle:(RewardCurrencyMessagingTextStyle)messagingTextStyle
                       rewardRounding:(RewardCurrencyRounding)rewardRounding
                       rewardCallback:(NSNumber * _Nullable (^)(NSString *, NSNumber * _Nullable, NSString * _Nullable))rewardCallback;

Obj-C-compatible initializer. currencyImageLocations accepts an NSInteger bitmask (OR the raw values of RewardCurrencyImageLocations constants).

Properties

`currencyName` (read-only)

@property (nonatomic, copy, readonly) NSString *currencyName;

let currencyName: String

The label shown next to reward amounts throughout the SDK (e.g. "points", "gems", "cash").

Default: "points"

`currencyCode` (read-only)

@property (nonatomic, copy, readonly, nullable) NSString *currencyCode;

let currencyCode: String?

A short code shown instead of or alongside currencyName when rewardCurrencyLabelStyle is .currencyCode (e.g. "PTS"). Has no effect when rewardCurrencyLabelStyle is .currencyImage or .currencyName.

Default: nil

`currencyCodePosition` (read-only)

@property (nonatomic, readonly) RewardCurrencyCodePosition currencyCodePosition;

let currencyCodePosition: RewardCurrencyCodePosition

Whether the currency code or name is rendered before (.leading) or after (.trailing) the numeric amount.

Default: .leading

`currencyPerDollar` (read-only)

@property (nonatomic, readonly) double currencyPerDollar;

let currencyPerDollar: Double

Conversion rate from dollars to your currency unit. A backend payout of $1.00 is multiplied by this value before display (e.g. 100.0 means $1 = 100 points).

Default: 100.0

`userPayoutPercentage` (read-only)

@property (nonatomic, readonly) double userPayoutPercentage;

let userPayoutPercentage: Double

The share of Promo, Boost, and BarcodeCollection payouts credited to the user, expressed as a decimal (e.g. 0.6 = 60%). Clamped to the range [0.4, 1.0] internally.

Default: 0.6

`currencyImage` (read-only)

@property (nonatomic, strong, readonly, nullable) UIImage *currencyImage;

let currencyImage: UIImage?

A custom icon displayed alongside reward amounts. When nil and rewardCurrencyLabelStyle is .currencyImage, the SDK shows its built-in coin icon. Provide @2x / @3x assets for Retina screens.

Default: nil

`currencyImageLocations` (read-only, Swift only)

let currencyImageLocations: RewardCurrencyImageLocations

Bitmask controlling which SDK screens show the currency icon. Combine values with | (e.g. .offerCell | .receiptTotalReward). From Obj-C, pass the integer bitmask to the designated initializer.

Default: .all (icon shown on all screens)

Option	Description
`.offerCell`	Icon shown next to reward amounts on offer cards.
`.receiptTotalReward`	Icon shown next to the total reward amount in the receipt summary header.
`.receiptBoost`	Icon shown on boost cards in the receipt summary.
`.receiptTask`	Icon shown on earn-task rows in the receipt summary.
`.all`	All of the above.

`rewardCurrencyLabelStyle` (read-only)

@property (nonatomic, readonly) RewardCurrencyLabelStyle rewardCurrencyLabelStyle;

let rewardCurrencyLabelStyle: RewardCurrencyLabelStyle

Controls how reward amounts are labeled on offer cards and the receipt summary.

Value	Display
`.currencyImage`	Icon + number (e.g. 🪙 100)
`.currencyCode`	Code + number (e.g. PTS 100)
`.currencyName`	Name + number (e.g. 100 points)

Default: .currencyImage

`rewardCurrencyMessagingTextStyle` (read-only)

@property (nonatomic, readonly) RewardCurrencyMessagingTextStyle rewardCurrencyMessagingTextStyle;

let rewardCurrencyMessagingTextStyle: RewardCurrencyMessagingTextStyle

Controls how SDK messaging copy (e.g. "Earn 100 points") refers to the currency.

Value	Example
`.currencyName`	"Earn 100 points"
`.currencyCode`	"Earn 100 PTS"
`.noAmount`	"Earn rewards"

Default: .currencyName

`rewardRounding` (read-only)

@property (nonatomic, readonly) RewardCurrencyRounding rewardRounding;

let rewardRounding: RewardCurrencyRounding

Whether reward amounts are rounded to a whole number (.whole) or shown with a decimal (.decimal).

Default: .whole

`rewardCallback` (read-only)

@property (nonatomic, copy, readonly) NSNumber * _Nullable (^rewardCallback)(NSString * _Nonnull context, NSNumber * _Nullable rewardAmount, NSString * _Nullable blinkReceiptId);

let rewardCallback: (_ context: String, _ rewardAmount: NSNumber?, _ blinkReceiptId: String?) -> NSNumber?

Called by the SDK on each reward event. The callback runs on the main thread — keep it fast and defer any heavy work (network, database) to a background queue.

`context`	Direction	`rewardAmount`	Expected return
`"ScanFinished"`	SDK asks host app	`nil`	Return the scan reward as `NSNumber`
`"Promo"`	SDK informs host app	Set by SDK	Return `nil`; credit `rewardAmount` to user
`"Boost"`	SDK informs host app	Set by SDK	Return `nil`; credit `rewardAmount` to user
`"BarcodeCollection"`	SDK informs host app	Set by SDK	Return `nil`; credit `rewardAmount` to user

See Production Reward Handling for implementation examples.

Appearance

A container that pairs a Theme with the SDK's rendering pipeline. Assign to BlinkEngageSDK.shared.appearance before presenting any SDK UI.

Declaration

@interface Appearance : NSObject

final class Appearance : NSObject

Initializers

`init()`

- (instancetype)init;

init()

Creates an Appearance that uses the SDK's built-in styling for every screen.

`init(theme:)`

- (instancetype)initWithTheme:(id<Theme> _Nullable)theme;

init(theme: Theme?)

Creates an Appearance backed by a custom theme. Passing nil produces the same result as the parameterless init().

Properties

`theme` (read-only)

@property (nonatomic, strong, readonly, nullable) id<Theme> theme;

let theme: Theme?

The theme the SDK queries for colors, font names, images, and text overrides. When nil, every SDK screen uses its built-in styling.

Default: nil

OffersWallViewController

The primary SDK view controller. Displays available offers or the user's clipped offers. Must be wrapped in a UINavigationController before presentation — the SDK pushes filtered offer lists and store screens onto that stack.

Declaration

@interface OffersWallViewController : UIViewController

class OffersWallViewController : UIViewController

Initializers

`init()`

- (instancetype)init;

convenience init()

Creates an offer wall showing all available offers (.all view type). Uses BlinkEngageSDK.shared.rewardConfig.

`init(offerWallViewType:)`

- (instancetype)initWithOfferWallViewType:(OfferWallViewType)offerWallViewType;

convenience init(offerWallViewType: OfferWallViewType)

Creates an offer wall with the specified view type. Uses BlinkEngageSDK.shared.rewardConfig.

`init(offerWallViewType:rewardCurrencyConfig:)`

- (instancetype)initWithOfferWallViewType:(OfferWallViewType)offerWallViewType
                      rewardCurrencyConfig:(BlinkEngageRewardConfig *)rewardCurrencyConfig;

init(offerWallViewType: OfferWallViewType, rewardCurrencyConfig: BlinkEngageRewardConfig)

Designated initializer. Pass an explicit rewardCurrencyConfig to keep reward copy stable for this presentation if you update BlinkEngageSDK.shared.rewardConfig at runtime.

Properties

`delegate`

@property (nonatomic, weak, nullable) id<OffersWallViewControllerDelegate> delegate;

weak var delegate: OffersWallViewControllerDelegate?

The delegate that receives offer wall events, including floating action button taps and clipped-offer count updates. See OffersWallViewControllerDelegate.

Default: nil

`offersType` (read-only)

@property (nonatomic, readonly) OfferWallViewType offersType;

let offersType: OfferWallViewType

The view type this instance was created with (.all or .clipped). Set at initialization; cannot be changed after creation.

OffersWallViewControllerDelegate

The delegate protocol for OffersWallViewController. All methods are optional.

Declaration

@protocol OffersWallViewControllerDelegate <NSObject>

protocol OffersWallViewControllerDelegate : AnyObject

Methods

`offerWallDidSelectFloatingAction(_:)` (optional)

- (void)offerWallDidSelectFloatingAction:(OffersWallViewController *)viewController;

optional func offerWallDidSelectFloatingAction(_ viewController: OffersWallViewController)

Called when the user taps the floating "Scan Receipt" button, including when the button appears on store and section offer lists pushed onto the navigation stack. Use this to start a BRScanManager scan session with scanOptions.enableBlinkEngage = true.

`offerWallShouldDisplayFloatingAction(_:)` (optional)

- (BOOL)offerWallShouldDisplayFloatingAction:(OffersWallViewController *)viewController;

optional func offerWallShouldDisplayFloatingAction(_ viewController: OffersWallViewController) -> Bool

Return false to hide the floating scan button entirely. Queried once when the view loads.

Default (when not implemented): true

`offerWall(_:didUpdateClippedOffersCount:)` (optional)

- (void)offerWall:(OffersWallViewController *)viewController
    didUpdateClippedOffersCount:(NSInteger)count;

optional func offerWall(_ viewController: OffersWallViewController, didUpdateClippedOffersCount count: Int)

Called on initial load and whenever the user clips or unclips an offer. Use count to update a badge on the "Saved" tab bar item or any other affordance that tracks the clipped count.

BlinkEngageSDK​

Type Methods​

start(debugMode:)​

Type Properties​

shared (read-only)​

Instance Properties​

user (read-only)​

rewardConfig​

appearance​

eventCallback​

Event Name Constants​

eventScanSessionStarted​

eventAdLoadingStarted​

eventPostScanViewed​

eventOfferWallViewed​

eventOfferDetailViewed​

eventOfferClipped​

Event Metadata Keys​

eventMetadataOfferTitle​

BlinkEngageUser​

Properties​

emailHash​

phoneHash​

clientUserId​

BlinkEngageRewardConfig​

Initializers​

init(rewardCallback:) (Swift)​

Obj-C Initializer​

Properties​

currencyName (read-only)​

currencyCode (read-only)​

currencyCodePosition (read-only)​

currencyPerDollar (read-only)​

userPayoutPercentage (read-only)​

currencyImage (read-only)​

currencyImageLocations (read-only, Swift only)​

rewardCurrencyLabelStyle (read-only)​

rewardCurrencyMessagingTextStyle (read-only)​

rewardRounding (read-only)​

rewardCallback (read-only)​

Appearance​

Initializers​

init()​

init(theme:)​

Properties​

theme (read-only)​

OffersWallViewController​

Initializers​

init()​

init(offerWallViewType:)​

init(offerWallViewType:rewardCurrencyConfig:)​

Properties​

delegate​

offersType (read-only)​

OffersWallViewControllerDelegate​

Methods​

offerWallDidSelectFloatingAction(_:) (optional)​

offerWallShouldDisplayFloatingAction(_:) (optional)​

offerWall(_:didUpdateClippedOffersCount:) (optional)​

BlinkEngageSDK

Type Methods

`start(debugMode:)`

Type Properties

`shared` (read-only)

Instance Properties

`user` (read-only)

`rewardConfig`

`appearance`

`eventCallback`

Event Name Constants

`eventScanSessionStarted`

`eventAdLoadingStarted`

`eventPostScanViewed`

`eventOfferWallViewed`

`eventOfferDetailViewed`

`eventOfferClipped`

Event Metadata Keys

`eventMetadataOfferTitle`

BlinkEngageUser

Properties

`emailHash`

`phoneHash`

`clientUserId`

BlinkEngageRewardConfig

Initializers

`init(rewardCallback:)` (Swift)

Obj-C Initializer

Properties

`currencyName` (read-only)

`currencyCode` (read-only)

`currencyCodePosition` (read-only)

`currencyPerDollar` (read-only)

`userPayoutPercentage` (read-only)

`currencyImage` (read-only)

`currencyImageLocations` (read-only, Swift only)

`rewardCurrencyLabelStyle` (read-only)

`rewardCurrencyMessagingTextStyle` (read-only)

`rewardRounding` (read-only)

`rewardCallback` (read-only)

Appearance

Initializers

`init()`

`init(theme:)`

Properties

`theme` (read-only)

OffersWallViewController

Initializers

`init()`

`init(offerWallViewType:)`

`init(offerWallViewType:rewardCurrencyConfig:)`

Properties

`delegate`

`offersType` (read-only)

OffersWallViewControllerDelegate

Methods

`offerWallDidSelectFloatingAction(_:)` (optional)

`offerWallShouldDisplayFloatingAction(_:)` (optional)

`offerWall(_:didUpdateClippedOffersCount:)` (optional)