Swift SDK

SDK for iOS and macOS.

Requirements

The WinWinKit SDK is available in native Swift and supports iOS 16 and macOS 13 or later.

Installation

Swift Package Manager

You can use Swift Package Manager to add WinWinKit to your Xcode project:

  1. In Xcode select “File” -> “Add Packages Dependencies”
  2. Enter the repository URL:
https://github.com/winwinkit/winwinkit-swift.git
  1. Press “Add Package”.

The library should be added to the Package Dependencies and you should be able to import WinWinKit in your source files.

Configuration

Configure the SDK with the API key and set the referral user’s App User Id.

import WinWinKit

Referrals.configure(apiKey: "your-api-key")
// Singleton can be used after configure(apiKey:) method has been called.
Referrals.shared.set(appUserId: "your-app-user-id")

Set the First Seen At

Recommended to set first seen at which is the date when the user was first seen in your app. This is used to evaluate user’s eligibility to claim code of another user. By default it is 7 days since the first seen at date.

If not set, the first seen at is the date the user was created in WinWinKit.

Referrals.shared.set(firstSeenAt: Date())

Update user properties

Is Premium

Update is premium property to track referring user’s stats and enable rewards activation on conversion.

Referrals.shared.set(isPremium: true)

For automatic updates of the is_premium flag, enable integration with RevenueCat. To do this, go to your project in WinWinKit and navigate to Settings -> Integrations page.

Metadata

Optionally set metadata to set user’s additional properties.

Referrals.shared.set(metadata: ["key": "value"])

User

User object contains all necessary information needed to display in the user interface.

Access the latest user object.

let user = Referrals.shared.user

Also available as a property on ReferralsObservableObject (see below).

Claim Code

Claim a code for a user. Code can be affiliate, promo or referral code.

let (user, rewardsGranted) = try await Referrals.shared.claimCode(code: "XYZ123")
 // Grant access to rewards in your app

Fetch Offer Code

let (offerCode, subscription) = try await Referrals.shared.fetchOfferCode(offerCodeId: "1234-5678")
// Display to the user what benefits offer code gives

Withdraw Credits

let (user, withdrawResult) = try await Referrals.shared.withdrawCredits(key: "extra-levels", amount: 5)

SwiftUI

The SDK provides convenient Observable object to interact and observe changes in SwiftUI views.

ReferralsObservableObject

Provides observable User object, methods and states for interacting with WinWinKit service.

@State var referralsObservableObject = Referrals.shared.observableObject

...

VStack {
    Text("Your referral code")
    Text(self.referralsObservableObject.user?.referralCode ?? "-")
      .font(.title3)
}

...

Button(action: {
    self.referralsObservableObject.claimCode(code: self.code)
}) {
    Text("Claim")
}

In SwiftUI only apps it is possible to build complete integration with only this observable object.

User Interface

The SDKs provide interface for interacting with WinWinKit APIs, but not the UI.

Thus you need to build the user interface for the referral feature in your app.

We plan to provide UI with the SDK in the future. Please let us know if that is your requirement to get started.

Delegate

Optionally set a delegate to receive events from the SDK.

let delegate = Delegate()
Referrals.shared.delegate = delegate

// Retain the delegate object to keep receiving events.

...


final class Delegate: ReferralsDelegate {

    init() {}

    func referrals(_ referrals: Referrals, receivedUpdated user: User?) {
        // Called every time the user is updated.
    }

    func referrals(_ referrals: Referrals, receivedError error: any Error) {
        // Received error when creating, updating or fetching the user.
    }
}

Setting the delegate is optional when using the observable object described above.

Error Handling

The SDK exposes ReferralsError enum type conforming to Error type.

Thrown or returned errors can be soft casted to ReferralsError enum type wherever received from the SDK. Additionally, there are convenience properties on ReferralsError enum type and states of ReferralsObservableObject for querying the error objects.

if let errorObjects = self.referralsObservableObject.claimCodeState.errorObjects {
    // TODO: failed to claim code - show error(s) to the user
}

Requirements

  • iOS 16.0+
  • macOS 13.0+
  • Xcode 15.0+
  • Swift 5.0+

Check out the SDK on GitHub