Free to Play (FTP) Support — iOS

Free to Play (FTP) Support — iOS

Free to Play (FTP) matchups allow users to enter matchups without risking money, earning tenant-defined rewards instead. FTP is supported across GYP (Games You Play), SYW (Sports You Watch), and tournaments depending on partner configuration.

Your app provides reward definitions and claim handling; Lucra handles UI, contest logic, settlement, and webhook delivery.

---

🎯 Key Concepts

LucraReward

A model describing a reward the user can earn:

• Title

• Description

• Icon URLs

• Metadata (SKU, expiration, type, etc.)

LucraRewardProvider

Your app implements this protocol to:

1. Return available rewards

2. Handle reward claim actions

Lucra calls this provider whenever:

• A user creates a Free to Play matchup

• A user claims a reward

• Rewards need to be displayed in Lucra UI

---

🧩 Implementing LucraRewardProvider

Create a class that implements the LucraRewardProvider Protocol:

public protocol LucraRewardProvider: AnyObject {
    /// Allows asynchronous provisioning of a set of rewards to be made available to users
    /// - Returns: [LucraReward]
    func availableRewards() async -> [LucraReward]
    
    /// Provides custom logic for claiming a specified reward upon completion of a matchup. This can be handled within the app or by redirecting the user to a web page, for example.
    /// - Parameters:
    ///     - reward: The reward to be redeemed
    func claimReward(reward: LucraReward)
    
    /// Invoked whenever a user interaction requires displaying the rewards they have earned.
    func viewRewards()
}

---

📌 Registering the Provider

On the LucraClient, call registerRewardProvider with this custom class to have Lucra populate this class with available rewards.

let provider = MyFTPRewardProvider()
lucraClient.registerRewardProvider(provider)

Without registration: 👉 No FTP matchups will show rewards.

---

🛠 Example Implementation

final class MyFTPRewardProvider: LucraRewardProvider {

    func availableRewards() async -> [LucraReward] {
        // Fetch from backend
        return [
            LucraReward(
                rewardId: "free_burger",
                title: "Free Burger",
                descriptor: "Get a free burger with any purchase.",
                iconUrl: URL(string: "https://example.com/burger.png"),
                bannerIconUrl: URL(string: "https://example.com/burger_big.png"),
                disclaimer: "*One per customer. Expires 12/31.",
                metadata: [
                    "type": "food",
                    "partner": "BurgerCo"
                ]
            )
        ]
    }

    func claimReward(reward: LucraReward) {
        // Navigate into your reward detail or redemption flow
        navigateToRewardScreen(reward)
    }
}

availableRewards() is async, so you can perform network calls.

---

🎁 How Rewards Flow

When creating an FTP matchup:

• Lucra calls availableRewards()

• User selects one reward

• Reward is attached to matchup

• Lucra records the selection

When a user wins a reward:

• Lucra notifies your backend via webhook

• Your backend grants the reward

• Lucra calls claimReward(reward:) on your provider

Your responsibility is to present the reward redemption UI.

---

🛰 Backend Requirements

• Backend Integration (https://docs.lucrasports.com/lucra-sdk/games-you-play-gyp/free-to-play/free-to-play-backend-integration)

---

👀 Example User Flow

1. User creates an FTP matchup

2. User chooses a reward

3. Contest settles

4. Lucra notifies your backend

5. User clicks on a reward and Lucra invokes claimReward()

6. Your app navigates user to the reward redemption flow

---

✔️ Integration Checklist

• Implement LucraRewardProvider

• Register with LucraClient

• Backend FTP webhook configured

• Available rewards returned correctly

• Reward claim navigation implemented

• Tested with sandbox matchups

Your Free to Play integration is complete.