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. It supports both Swift and Objective-C.

The SDK provides two model classes; Conversion and ConversionItem. The Partnerize class is also used to provide functionality for dealing with inbound clicks, the combination of these classes 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.

Quick Start

Installation

CocoaPods

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

target :YourTargetName do
  pod 'Partnerize'
end

Carthage

  1. Add github "PerformanceHorizonGroup/partnerize-mobile-sdk-ios" to your Cartfile.
  2. Run carthage update.
  3. 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.
  4. 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

  1. 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

  1. Download Partnerize for iOS and extract the zip.
  2. Go to your Xcode project's "General" settings. Drag Partnerize.framework to the "Embedded Binaries" section. Make sure "Copy items if needed" is selected and click Finish.
  3. Create a new “Run Script Phase” in your app’s target’s “Build Phases” and paste the following snippet in the script test field:

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Partnerize.framework/strip-frameworks.sh"

Example app

There is an example app provided here for Swift.

Handling inbound clicks

When an inbound intent from a mobile web browser or iOS app launches your iOS app via a deep link. This prepares an internal conversion object using Universal Link for further use and returns a new url containing original url with the app_clickref parameter stripped when conversion is completed.

To return the full click object, use the following method.


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

       if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
           let click = try? Partnerize.beginConversion(userActivity.webpageURL)

           let clickRef = click?.clickRef
           let camRef = click?.camRef
           let destination = click?.destination
           let utmParams = click?.utmParams
           let meta = click?.meta
       }
 }

Alternatively, if just the destination URL is required, use the following method.

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

       if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
           let url = try? Partnerize.beginConversion(with: userActivity.webpageURL)
       }

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. The completion block returns the status of the conversion and an error.

Partnerize.completeConversion { isSuccess, error in
  if isSuccess {
    print("conversion logged")
  }
}

Resources

Click

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

     let clickRef = click?.clickRef
     let camRef = click?.camRef
     let destination = click?.destination
     let destinationMobile = click?.destinationMobile
     let utmParams = click?.utmParams
     let meta = click?.meta

Conversion

The Conversion class describes attributes and items within a conversion. This is accessed as a property on the Partnerize class.

    Partnerize.conversion?.adRef = "myAddRef"
    Partnerize.conversion?.pubRef = "myPublisherRef"
    Partnerize.conversion?.country = "US"
    Partnerize.conversion?.currency = "USD"
    Partnerize.conversion?.conversionRef = "myConversionRef"
    Partnerize.conversion?.custRef = "myCustomerRef"
    Partnerize.conversion?.voucher = "25OFF"
    Partnerize.conversion?.tsource = PHGAffiliateTrafficSource //"Affiliate"
    Partnerize.conversion?.customerType = .PHGNew
    Partnerize.conversion?.tmetric = PHGCheckoutConversionMetric // "Checkout"
    Partnerize.conversion?.metadata = ["payment_type" : "crypto_currency"]

    Partnerize.conversion?.items = [ConversionItem(value: "11.99", category: "Shoes", quantity: "1", sku: "mySku")]

Clearing the Clickref

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

  Partnerize.conversion?.clearClickref()

TrafficSource

The PHGConversionTrafficSource constants such as PHGAffiliateTrafficSource 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 PHGConversionMetric constants such as PHGCheckoutConversionMetric 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 associated; 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"),
    ]  

    conversionItems.first?.metadata = ["season" : "winter"]

Development Mode

During development of your iOS app you may need to debug the requests being made.

  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

License

Apache-2.0

Release Notes

Release notes can be found here