iOS Activation — Reward Currency

All reward display configuration lives in BlinkEngageRewardConfig. Create one instance and assign it to BlinkEngageSDK.shared.rewardConfig before presenting any SDK UI.

---

Quick Start (Defaults)

A zero-argument initializer gives sensible defaults — icon style, "points" label, 100:1 rate, 60% payout, no callback:

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig()
// Rows show: 🪙 1,234
// Toasts say: "You earned 250 points for this receipt!"

---

Label Style

rewardCurrencyLabelStyle controls how reward amounts appear in list rows.

.currencyImage — Icon + Digits (Default)

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "points",
    rewardCurrencyLabelStyle: .currencyImage   // 🪙 1,234
)

.currencyName — Digits + Text Label

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "gems",
    rewardCurrencyLabelStyle: .currencyName,           // 1,234 gems
    rewardCurrencyMessagingTextStyle: .currencyName    // "You earned 250 gems for this receipt!"
)

currencyName is trimmed and truncated to 8 characters. Empty input falls back to "points".

.currencyCode — Currency Symbol

// Leading symbol: $1,234
BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyCode: "$",
    rewardCurrencyLabelStyle: .currencyCode,
    rewardCurrencyMessagingTextStyle: .currencyCode    // "You earned $250 for this receipt!"
)

// Trailing symbol: 1,234€
BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyCode: "€",
    currencyCodePosition: .trailing,
    rewardCurrencyLabelStyle: .currencyCode,
    rewardCurrencyMessagingTextStyle: .currencyCode
)

If currencyCode is empty or missing after trimming, the SDK falls back to .currencyName automatically.

---

Messaging Style

rewardCurrencyMessagingTextStyle controls toast and headline copy ("You earned X for this receipt!") independently from the row label style.

Style	Example toast
.currencyName	"You earned 250 points for this receipt!"
.currencyCode	"You earned $250 for this receipt!"
.noAmount	"You earned a reward for this receipt!"

Use .noAmount when you prefer not to highlight exact amounts in celebratory copy. Rows still show the numeric amount:

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "points",
    rewardCurrencyLabelStyle: .currencyName,
    rewardCurrencyMessagingTextStyle: .noAmount
    // Rows: "1,234 points" — Toasts: "You earned a reward for this receipt!"
)

---

Custom Reward Icon

Replace the built-in coin icon by setting currencyImage. Use .alwaysTemplate rendering so the SDK can tint it for light and dark mode:

let icon = UIImage(named: "gem-icon")?.withRenderingMode(.alwaysTemplate)

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "gems",
    currencyImage: icon
)

Restricting Icon Surfaces

currencyImageLocations is an OptionSet that controls which SDK surfaces show the icon. By default it appears everywhere:

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "gems",
    currencyImage: icon,
    currencyImageLocations: [.offerCell, .receiptTotalReward]  // icon only on these surfaces
)

Pass [] to hide the icon everywhere while keeping other config intact.

---

Conversion Rate and Payout

Parameter	Default	Description
currencyPerDollar	100.0	Units per US dollar. SDK multiplies dollar payouts by this value and rounds up (ceil).
userPayoutPercentage	0.6	Fraction of boost/UGC rewards paid to the user. Clamped to 0.4...1.0.

// High-value virtual currency: 1,000 units/dollar, 80% payout
// A $2.50 payout → 2,500 × 0.8 = 2,000 coins shown to user
BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "coins",
    currencyPerDollar: 1000,
    userPayoutPercentage: 0.8,
    rewardCurrencyLabelStyle: .currencyName,
    rewardCurrencyMessagingTextStyle: .currencyName
)

// Real-currency cashback: 1:1 rate, 100% payout
BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyCode: "$",
    currencyPerDollar: 1,
    userPayoutPercentage: 1.0,
    rewardCurrencyLabelStyle: .currencyCode,
    rewardCurrencyMessagingTextStyle: .currencyCode,
    rewardCallback: { context, _, _ in
        context == "ScanFinished" ? NSNumber(value: 1) : nil
    }
)

---

Reward Callback

The callback is invoked each time the user earns a reward. It receives a context string, an optional rewardAmount, and the blinkReceiptId for the current receipt session.

BlinkEngageSDK.shared.rewardConfig = BlinkEngageRewardConfig(
    currencyName: "points",
    currencyPerDollar: 100.0,
    rewardCallback: { context, rewardAmount, blinkReceiptId in
        switch context {
        case "ScanFinished":
            // SDK asks the host app for the base scan reward — return an NSNumber
            return NSNumber(value: 10)
        case "Promo", "Boost", "BarcodeCollection":
            // SDK informs the host app of the earned amount — credit it and return nil
            print("Earned \(rewardAmount ?? 0) via \(context)")
            return nil
        default:
            return nil
        }
    }
)

Context	SDK behavior	Host app response
"ScanFinished"	Asks for the scan reward	Return NSNumber with the amount
"Promo"	Reports earned promo reward	Credit rewardAmount, return nil
"Boost"	Reports earned boost reward	Credit rewardAmount, return nil
"BarcodeCollection"	Reports barcode capture reward	Credit rewardAmount, return nil

The default is a no-op callback ({ _, _, _ in nil }).

---

Updating Config at Runtime

All BlinkEngageRewardConfig properties are let. To change a setting after initial setup, create a new instance and reassign:

let updated = BlinkEngageRewardConfig(
    currencyName: "stars",
    currencyPerDollar: 200
)
BlinkEngageSDK.shared.rewardConfig = updated

The updated config takes effect the next time an SDK view is presented. It does not refresh views already on screen.

---

Objective-C

Objective-C callers use the full memberwise initializer. Combine currencyImageLocations constants with bitwise OR:

BlinkEngageRewardConfig *config = [[BlinkEngageRewardConfig alloc]
    initWithCurrencyName:@"coins"
            currencyCode:@"$"
    currencyCodePosition:RewardCurrencyCodePositionLeading
       currencyPerDollar:500
    userPayoutPercentage:0.7
           currencyImage:[UIImage imageNamed:@"coin-icon"]
  currencyImageLocations:BlinkEngageRewardConfig.imageLocationOfferCell
                       | BlinkEngageRewardConfig.imageLocationReceiptTotalReward
        rewardLabelStyle:RewardCurrencyLabelStyleCurrencyCode
      messagingTextStyle:RewardCurrencyMessagingTextStyleCurrencyCode
        rewardRounding:RewardCurrencyRoundingWhole
          rewardCallback:^NSNumber *(NSString *context, NSNumber *amount, NSString *blinkReceiptId) {
              if ([context isEqualToString:@"ScanFinished"]) return @10;
              return nil;
          }];

BlinkEngageSDK.shared.rewardConfig = config;