Tracking In-App Conversions (Interim)
The iOS SDK doesn't have a trackConversion method yet. Until it does, you can send in-app
purchases and signups to Lucia with one HTTPS request. It's the same request the
web SDK's trackConversion makes, so the data lands in
the same place.
What changes later: when native in-app events ship, this request becomes a single SDK call. You'll swap the function below for that call. Nothing else in your app or dashboard changes.
How it works
- When the SDK starts, it returns the device's Lucia ID.
- When someone converts, you send the conversion with that Lucia ID.
- Lucia adds the conversion to that device's profile, next to its other activity.
The Lucia ID stays the same for the device across app launches, so you can save it once and reuse it.
Send it from the app
import Foundation
enum LuciaConversions {
static func track(
luciaID: String,
tag: String, // e.g. "purchase", "signup"
amount: Double, // 0 if it has no value
currency: String = "USD", // ISO-4217 code
details: [String: String] = [:] // anything you want in reports
) async throws {
guard let apiKey = Bundle.main.infoDictionary?["LuciaSDKKey"] as? String else { return }
var request = URLRequest(url: URL(string: "https://api.luciaprotocol.com/api/sdk/conversion")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue(apiKey, forHTTPHeaderField: "X-API-KEY")
request.httpBody = try JSONSerialization.data(withJSONObject: [
"lid": luciaID,
"tag": tag,
"amount": amount,
"currency": currency,
"event": details,
])
let (_, response) = try await URLSession.shared.data(for: request)
guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode) else {
throw URLError(.badServerResponse)
}
}
}
Save the Lucia ID when the SDK starts, then call track after a successful purchase:
case .success(let luciaID):
UserDefaults.standard.set(luciaID, forKey: "luciaID")
// later, after StoreKit confirms the purchase
if let luciaID = UserDefaults.standard.string(forKey: "luciaID") {
try await LuciaConversions.track(
luciaID: luciaID, tag: "purchase", amount: 9.99, currency: "USD",
details: ["product": "pro_monthly"]
)
}
Or send it from your server
If purchases are confirmed on your backend (recommended for subscriptions and refunds), send the Lucia ID to your server along with the user, and post the conversion from there:
curl -X POST https://api.luciaprotocol.com/api/sdk/conversion \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{"lid":"LUCIA_ID","tag":"purchase","amount":9.99,"currency":"USD","event":{"product":"pro_monthly"}}'
Fields
| Field | Required | What to send |
|---|---|---|
lid | Yes | The Lucia ID returned when the SDK started |
tag | Yes | A name for the conversion, such as purchase or signup |
amount | No | The value. Use 0 if it has none |
currency | No | An ISO-4217 code like USD or EUR, or a supported crypto symbol. Leave it out to use your workspace currency |
event | No | Extra details as text key/value pairs |
Know the limits
- The SDK must have started. No Lucia ID means nothing to attach the conversion to. If the user declined tracking or is in a region where the SDK is off, skip the request.
- Campaign credit depends on the profile. The conversion is recorded on the device's profile straight away. Lucia doesn't yet see which ad led to an app install, though, so the conversion is credited to a campaign only when Lucia already links that profile to one.
- Check the response. Unlike the web SDK, your code sees the reply. A
400means a field was wrong, for example an unsupported currency.