Introduction

The Partnerize iOS SDK enables your app to capture in-app referrals and accurately attribute subsequent sales. It simplifies tracking across web-to-app and app-to-app flows, providing seamless integration for recording conversions.

Minimum Requirements

  • iOS 15.0+
  • Xcode 26.0+
  • Swift Tools 6.2+

Installation

Add the SDK via Swift Package Manager (recommended) or manually.

Swift Package Manager

  1. In Xcode: File → Add Package Dependencies…
  2. Enter https://github.com/PerformanceHorizonGroup/partnerize-mobile-sdk-ios
  3. Choose the latest tag (e.g., 3.0.1) and add the package.
  4. import PartnerizeSDK where needed.

Manual

  1. Download the framework zip from https://github.com/PerformanceHorizonGroup/partnerize-mobile-sdk-ios
  2. Drag your .xcframework into the Xcode project navigator and check "Copy items if needed" / "Copy files to destination" depending on version of Xcode. Ensure that their app target is also selected.
  3. Ensure that under Target -> Build Phases → Link Binary With Libraries, they see the framework is listed
  4. Ensure under Target → General → Frameworks, Libraries, and Embedded Content the .xcframework is added and is set to "Embed & Sign"
  5. At this point, they should be able to do an 'import PartnerizeSDK' into a class file and start using the SDK.

CocoaPods is deprecated from 3.0.0 onward (2.0 remains available).

Quick Start

Initialise the SDK

Create an instance per platform you need. Partnerize does not require an API key; Ascend does.

import PartnerizeSDK

// Partnerize
let sdkPartnerize = PartnerizeTracking<Partnerize>(
    configuration: Configuration(asyncTimeout: 10)
)

// Ascend
let sdkAscend = PartnerizeTracking<Ascend>(
    configuration: Configuration(asyncTimeout: 10), 
    apiKey: "demo api key"
)

Handle Inbound Clicks

Process incoming tracking URLs and optionally persist the attribution for later conversions.

let attribution = try sdkPartnerize.captureAttribution(
    url: inboundUrl,
    persist: true // default; set false to avoid storing
)
  • Partnerize: PartnerizeAttribution (clickRef: String?)
  • Ascend: AscendAttribution (clickId: Int?, gClickId: String?) — if present, clickId must be numeric; gClickId alone is accepted.
  • Partnerize storage: newest valid clickRef overwrites the previous one.
  • Ascend storage: valid click IDs and gclick IDs are appended until cleared.

Examples:

  • Partnerize: https://example.com/deeplink?clickref=abc123
  • Ascend: myapp://open?click_id=42&gclick_id=g-1 or myapp://open?gclick_id=g-2

Storage behavior examples:

Partnerize overwrites:

sdkPartnerize.captureAttribution(url: URL(string: "…?clickref=abc123")!, persist: true)
sdkPartnerize.captureAttribution(url: URL(string: "…?clickref=xyz999")!, persist: true)
sdkPartnerize.getStoredAttribution().clickRef // "xyz999"

Ascend appends:

sdkAscend.captureAttribution(url: URL(string: "…?click_id=42&gclick_id=g-1")!, persist: true)
sdkAscend.captureAttribution(url: URL(string: "…?gclick_id=g-2")!, persist: true)
sdkAscend.getStoredAttribution().clickIds  // [42]
sdkAscend.getStoredAttribution().gClickIds // ["g-1", "g-2"]

Post Conversions

Build a platform-specific conversion, then call completeConversion. Stored attribution is injected automatically; override with alternateAttributionData if needed.

var conversion = PartnerizeConversion(
    conversionRef: "conv_001",
    pubRef: "publisher_001",
    adRef: "advertiser_001",
    country: "GB",
    currency: "GBP",
    custRef: "customer_001",
    voucher: "VOUCHER123",
    tsource: "email_campaign",
    tmetric: "purchase",
    customerType: .new,
    items: [
        ConversionItem(value: 49.99, category: "Shoes", quantity: 1, sku: "SKU-001")
    ],
    metadata: ["utm_source": "newsletter"]
)

let result = try await sdkPartnerize.completeConversion(conversion)
// result: PartnerizeConversionResult (conversionId: String)

Callback variant:

sdkPartnerize.completeConversion(conversion) { result in
    print(result)
}

Error handling (async/await):

do {
    let result = try await sdkPartnerize.completeConversion(conversion)
    print(result)
} catch {
    print("Conversion failed: \(error)")
}

Stored Attribution Utilities

  • getStoredAttribution() → platform-specific stored attribution.
  • clearStoredAttribution() → removes stored attribution.

Use these to inspect or reset attribution state between sessions or logout flows. Remember: Partnerize overwrites; Ascend appends until cleared.

Snippets:

let stored = sdkPartnerize.getStoredAttribution()
sdkPartnerize.clearStoredAttribution()

Logging

Enable built-in logging or provide your own logger:

sdkPartnerize.loggingEnabled = true

struct MyLogger: PartnerizeLogger {
    func log(_ message: String) { print(message) }
}
sdkPartnerize.logger = MyLogger()

Partnerize Platform

Initialise with:

let sdkPartnerize = PartnerizeTracking<Partnerize>(
    configuration: Configuration(asyncTimeout: 10)
)

Attribution

  • PartnerizeAttribution: returned by captureAttribution; fields: clickRef: String?
  • PartnerizeStoredAttribution: returned by getStoredAttribution; fields: clickRef: String?
  • Storage: captureAttribution(..., persist: true) overwrites the stored clickRef with the newest valid inbound URL.

Conversion

PartnerizeConversion is a value type; set fields directly. Stored clickRef is injected by the SDK unless you override with alternateAttributionData.

Key fields:

  • conversionRef, pubRef, adRef, country, currency, custRef, voucher, tsource, tmetric, customerType
  • fulfilmentDate, fulfilmentStartDate (encoded as ISO8601)
  • items: [ConversionItem]?
  • metadata: [String: String]?

Example:

var conversion = PartnerizeConversion(
    conversionRef: "conv_001",
    pubRef: "publisher_001",
    adRef: "advertiser_001",
    country: "GB",
    currency: "GBP",
    items: [ConversionItem(value: 9.99, category: "Tops", quantity: 2)]
)
conversion.fulfilmentDate = Date() // encoded as ISO8601

ConversionResult

PartnerizeConversionResult

— fields: conversionId: String

Ascend Platform

Initialise with:

let sdkAscend = PartnerizeTracking<Ascend>(
    configuration: Configuration(asyncTimeout: 10), 
    apiKey: "demo api key"
)

Attribution

  • AscendAttribution: returned by captureAttribution; fields: clickId: Int?, gClickId: String?
  • AscendStoredAttribution: returned by getStoredAttribution; fields: clickIds: [Int], gClickIds: [String]
  • Storage: captureAttribution(..., persist: true) appends new IDs; multiple values are kept until you clear them.

Conversion

AscendConversion (Codable) has required order details; click IDs are injected from storage unless overridden.

Required:

  • orderId: String
  • items: [AscendItem]
  • created: String (datetime, e.g., yyyy-MM-dd HH:mm:ss)
  • currency: String

Optional:

  • publisherId: Int
  • type: TransactionType (default .sale)
  • newToFile: Bool?
  • coupons: [String]?
  • segment: String?

Example:

let items = [
    AscendItem(id: "item_001", amount: 49.99, quantity: 1, category: "Tops")
]

let conversion = AscendConversion(
    orderId: "order_001",
    items: items,
    created: "2024-01-01 12:00:00",
    currency: "GBP",
    publisherId: 1234,
    newToFile: true,
    coupons: ["WELCOME10"],
    segment: "vip"
)

let result = try await sdkAscend.completeConversion(conversion)
// result: AscendConversionResult (message: String)

ConversionResult

AscendConversionResult

— fields: message: String

License

Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0

Support

If you encounter issues, email: support@partnerize.com

Include:

  • Steps to reproduce
  • URLs used
  • Logger output
  • SDK version

Release Notes

Release notes can be found here