Introduction

The iOS Mobile SDK allows you to capture in-app referrals, and easily record any sales that occur on the back of these referrals within your iOS application. The SDK enables the following features within your iOS app:

Click reference retrieval from inbound requests.
Conversion creation with a range of attributes including custom metadata.
Conversion item support for accurate shopping basket representation.
Deep linking support for Web to App and App to App.

These docs are specifically for version 2 of the SDK. If you're still using version 1.X, please find the legacy docs here.

Most public methods use the Swift Result type and can return a PartnerizeError.

Quick Start

Installation

CocoaPods

Add the Partnerize pod into your Podfile and run pod install.

target :YourTargetName do
  pod 'Partnerize', '~> 2.0'
end

Carthage

Add github "PerformanceHorizonGroup/partnerize-mobile-sdk-ios" to your Cartfile.
Run carthage update.
Go to your Xcode project's "General" settings. Drag Partnerize.framework from Carthage/Build/iOS to the "Embedded Binaries" section. Make sure “Copy items if needed” is selected and click Finish.
After verifying your project compiles, switch over to Build Phases and add a new Run Script build phase by clicking the + in the top left of the editor. Add the following command:

/usr/local/bin/carthage copy-frameworks

Click the + under Input Files and add an entry for Partnerize framework:

$(SRCROOT)/Carthage/Build/iOS/Partnerize.framework

This build phase isn’t required for your project to run. However, it’s a workaround for an App Store submission bug where apps with frameworks that contain binary images for the iOS simulator are automatically rejected.

The carthage copy-frameworks command strips out these extra architectures.

Manual Installation

Download Partnerize for iOS and extract the zip.
Go to your Xcode project's "General" settings. Drag Partnerize.xcframework to the "Embedded Binaries" section. Make sure "Copy items if needed" is selected and click Finish.
For more information view this guide

Handling inbound clicks

When an inbound intent from a mobile web browser or iOS app launches your iOS app via a deep link, use the method handleInboundURL(url). One synchronous, and one asynchronous. Which one you use is up to you but note the synchronous will block and therefore impact your app launch time.

In addition, Partnerize will also store the clickRef received locally. This is then used later to post conversions. You can use the parameter persistClickRef in both examples to override the default behaviour, if you wish to store this clickRef yourself.

Synchronous

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {

    if let url = application.userActivity?.webpageURL, userActivity.activityType == NSUserActivityTypeBrowsingWeb {

        let result = Partnerize.handleInboundURL(url)
        switch result {
        case .success(let click):
            print(click)
        case .failure(let error):
            print(error)
        }
    }
}

Asynchronous

Partnerize.handleInboundURL(url) { result in
  switch result {
  case .success(let click):
    print(click)
  case .failure(let error):
    print(error)
  }
}

Posting Conversions to Partnerize

Once a conversion has been constructed and is ready to be recorded, it be can be sent to Partnerize using the following method

let conversion = Conversion(conversionRef: "conversionRef")
Partnerize.completeConversion(conversion) { result in
    switch result {
    case .success(let conversionResult):
        print(conversionResult.conversionId)
    case .failure(let error):
        print(error)
    }
}

Resources

Click

The Click class describes attributes and items within a click. This is returned from the method Partnerize.handleInboundURL(conversionUrl).

  let clickRef: String = click.clickRef
  let camRef: String = click.camRef
  let destination: URL = click.destination
  let destinationMobile: URL? = click.destinationMobile
  let meta: [String:String] = click.meta
  let utmParams: [String:String] = click.utmParams

Conversion

The Conversion class describes attributes and items within a conversion. This is constructed then passed into the completeConversion method.

let conversion = Conversion(
    conversionRef: "conversionRef",
    pubRef : "pubRef",
    adRef :"adRef",
    country : "USA",
    currency : "USD",
    custRef : "custRef",
    voucher : "voucher",
    tsource : "Email",
    tmetric : "Booked",
    customerType : .new,
    items: [ConversionItem(value: 10, category: "Shoes")],
    metadata : ["hello": "world"])

Clearing the Clickref

It may be necessary to clear the click ref, this can be done with the following.

  Partnerize.clearClickref()

TrafficSource

The TrafficSource constants such as TrafficSource.affiliate are for used for setting the traffic source on a conversion. Raw strings can also be used however, the Partnerize platform only accepts a predefined list of traffic sources.

CustomerType

This enum can either be CustomerType.existing or CustomerType.new, and is used for setting the customer type on a conversion.

ConversionMetric

The ConversionMetric constants such as ConversionMetric.checkout are for use for setting the conversion metric on a conversion. Raw strings can also be used however, the Partnerize platform only accepts a predefined list of traffic sources.

`ConversionItem`

The ConversionItem class is a representation of an item within a Conversion to better represent a shopping basket. A ConversionItem requires a value and category for each item however additional attributes can be included; quantity, sku as well as custom metadata similar to conversions.

let conversionItems = [
      ConversionItem(value: 9.99, category: "Tops"),
      ConversionItem(value: 9.99, category: "Tops", quantity: 1),
      ConversionItem(value: 9.99, category: "Shoes", quantity: 3, sku: "TRA-SPT-FIV"),
    ]

Development Mode

During development of your iOS app you may need to debug the requests being made. This can be done by adding the following key/value to your conversion metadata.

  conversion.metadata = ["development_mode" : "yes"]

Logging

Logging may also be useful for debugging, this can help track errors when using the Partnerize SDK. This can be enabled like so.

  Partnerize.isLoggingEnabled = true

In addition to this you can also inject a custom Logger implementation. This will help you understand what the SDK is doing and will help if any issues need raised. By default the Partnerize SDK will just print any logged messages. Below is an example of how to create and use your own PartnerizeLogger.

class MyLogger: PartnerizeLogger {
  func log(_ message: String) {
      print(message)
  }
}

...

Partnerize.logger = MyLogger()

Error Handling

Any error coming back will be a Partnerize Error. This can be handle in the following manner:

switch error {
  case .unknown:
     print("Something went really wrong")
  case .invalidJsonPayload(missingKeys: let missingKeys):
     print(missingKeys)
  case .noClickRef:
     print("Missing clickRef")
  case .invalidUrl:
     print("I passed in an invalid URL")
  case .timeout:
     print("The request timed out, maybe try again")
}

Configuration

The Partnerize SDK exposes a way to configure timeouts for the various requests (in seconds). This is done with the Partnerize.configure(options) method. Any method that uses a completion handler will use the asyncTimeout parameter, whilst only Partnerize.handleInboundURL(url) will use syncTimeout.

By default the values are: asyncTimeout: 10 syncTimeout: 1

let options = PartnerizeOptions(asyncTimeout: 30, syncTimeout: 20)
Partnerize.configure(with: options)

License

Apache-2.0

Support

If you encounter any issues please email support@partnerize.com with:

Steps to reproduce
Any URLs used
Logger output
The SDK Version embedded in your project

Release Notes

Release notes can be found here

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search