SaaSquatch Help Center

An installation walkthrough for the iOS SDK, explanations of common usage cases, and code examples.

In this article we're going to add the SDK into our project and start using it to interface with Referral SaaSquatch.

Installation

The Referral SaaSquatch mobile SDK for iOS is available through the industry standard CocoaPods format.

CocoaPods is a dependency manager for Swift and Objective-C projects designed so that instead of having to manually import files to your project, CocoaPods does it for you.

Install CocoaPods

If you do not have CocoaPods installed on your system, install it using the following Terminal command:

$ sudo gem install cocoapods

Navigate to the directory of the Xcode project you would like to install our SDK into.

If you do not already have a Podfile there, create one using the following Terminal command:

$ pod init

Edit the Podfile

Latest Version: Please make sure you are using the latest version of the SaaSquatch CocoaPod in your project.

Version info for Swift CocoaPod
Version info for Objective-C CocoaPod

For Swift projects; add the following to your Podfile:

# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'

target 'CocoapodsTest' do
  # Comment this line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!

  # Pods for CocoapodsTest
  pod 'saasquatch-sdk-swift', '~> 1.1.1' 
end

For Objective-C; projects add the following to your Podfile:

# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'

target 'CocoapodsTest' do
  # Comment this line if you're not using Swift and don't want to use dynamic frameworks
  # use_frameworks!

  # Pods for CocoapodsTest
  pod 'saasquatch-sdk-objectivec', '~> 1.0.4'
end

Save and close the Podfile and run $ pod install.

Including our Pod

Within your project's workspace, ex. CocoapodsTest.xcworkspace, you will find both your project and the Pod project contain our SDK.

If your project is in Swift, add this to the top of your files:

import saasquatch

If your project is in Objective-C, add this to the top of your files:

#import "saasquatch.h"

Note: you may receive an error that indicates no module called saasquatch was found. This just means your project needs to be built with the pod. Simply clean your project and build it again and this error will disappear.

Usage

The Referral SaaSquatch iOS SDK allows us to:

  • Register your users with Referral SaaSquatch to track their referrals.
  • Track your user's referrals with Referral SaaSquatch.
  • Fetch information about your users, referral codes, and rewards.

To demonstrate how to use the SDK, let's walk through registering a user with Referral SaaSquatch and making a referral as demoed in our Sample App. This can be achieved by following these steps:

  • Register a new user with Referral SaaSquatch.
  • Lookup a referral code provided by your user during sign up.
  • Apply the referral to your user's account.
  • Show your user information about the user who referred them.

Import Saasquatch

Import the Saasquatch class at the top of your file.

import saasquatch

Signing Requests

Mobile SDK methods make use of our Open Endpoints API functionality. More information about the limitations of these calls can be found on our Open Endpoints page.

Open Endpoint calls are signed with JWTs. Read more about how to sign JWTs to make secure requests to Referral SaaSquatch on our JWT page.

Upsert a user with Referral SaaSquatch

User Upsert

  • Also similar to "Register a User"
  • If we are updating a users info, use the current userId and accountId. Below, we are using user upsert to create a new user

  • We set the userInfo field first.

// This is your tenant alias which identifies you with Referral SaaSquatch
let tenant = "acpiocfij942"

// We register our user internally, then pass the user's information to Referral SaaSquatch
let userId = "000001"
let accountId = "000001"

let userInfo: [String: AnyObject] = [
    "id": userId,
    "accountId": accountId,
    "email": "claire@lallybroch.com",
    "firstName": "Claire",
    "lastName": "Fraser",
    "locale": "en_US",
    "referralCode": "CLAIREFRASER"]

-Now we create/update our user with Referral SaaSquatch

// Upsert a user with Referral Saasquatch
Saasquatch.userUpsert(tenant, withUserID: userId, withAccountID: accountId, withToken: token, withUserInfo: userInfo,
    completionHandler: {(userInfo: AnyObject?, error: NSError?) in

        // Code to be executed after the async call returns
})
  • This is our completionHandler

    completionHandler: {(userInfo: AnyObject?, error: NSError?) in
    
     // First, check if an error occurred
     if error != nil {
         //handle errors
     }
    
     // We would like to save the share links returned by the Referral SaaSquatch server.
     guard let shareLinks = userInfo?["shareLinks"] as? [String: AnyObject],
         let shareLink = shareLinks["shareLink"] as? String,
         let facebookShareLink = shareLinks["mobileFacebookShareLink"] as? String,
         let twitterShareLink = shareLinks["mobileTwitterShareLink"] as? String, else {
             return
     }
    }
    

Register a user with Referral SaaSquatch

To register a user, we provide user information to Referral SaaSquatch. We provide our tenant alias which identifies our app. A userId from our system is passed to SaaSquatch to uniquely identify our users. We pass in an accountId, which Referral SaaSquatch uses to group users together; see Shared vs Solo Accounts to see what you should use here. Lastly, we provide a valid JSON object containing information about our user. For a description of the available userInfo fields, please see SaaSquatch docs. Here is an example:

// This is your tenant alias which identifies you with Referral SaaSquatch
let tenant = "acpiocfij942"

// We register our user internally, then pass the user's information to Referral SaaSquatch
let userId = "000001"
let accountId = "000001"

let userInfo: [String: AnyObject] = [
    "id": userId,
    "accountId": accountId,
    "email": "claire@lallybroch.com",
    "firstName": "Claire",
    "lastName": "Fraser",
    "locale": "en_US",
    "referralCode": "CLAIREFRASER"]

In this example, we assign an id of 000001 since Claire is our first user. We pass her email, first and last names, and her locale to Referral SaaSquatch. We have also assigned her a referral code so she can use it to refer new users. When a new user signs up with referral code "CLAIREFRASER" she will get the credit.

Now we can register our user with Referral SaaSquatch using this call:


// Register a user with Referral Saasquatch
Saasquatch.registerUserForTenant(tenant, withUserID: userId, withAccountID: accountId, withToken: token, withUserInfo: userInfo,
    completionHandler: {(userInfo: AnyObject?, error: NSError?) in

        // Code to be executed after the async call returns
})

We provide a completionHandler which will be called with userInfo and error. userInfo contains the returned information about the user. error contains a description of the error, if any, and an error code indicating the HTTP status code returned by the server. If error is nil then userInfo will exist and vice versa.

In our completionHandler, we will parse through the returned data and save anything useful for later.

completionHandler: {(userInfo: AnyObject?, error: NSError?) in

    // First, check if an error occurred
    if error != nil {
        //handle errors
    }

    // We would like to save the share links returned by the Referral SaaSquatch server.
    guard let shareLinks = userInfo?["shareLinks"] as? [String: AnyObject],
        let shareLink = shareLinks["shareLink"] as? String,
        let facebookShareLink = shareLinks["mobileFacebookShareLink"] as? String,
        let twitterShareLink = shareLinks["mobileTwitterShareLink"] as? String, else {
            return
    }
}

Make the referral

Once the user is registered and any useful information returned in userInfo has been saved away, we will make their referral with Referral SaaSquatch. We'll call applyReferralCode with the code our user gave us and their userId, accountId and token. The function validates the referral code. If the code is successful the reward information will be returned in userInfo, or if the code cannot be applied to the account an error will be returned.

Saasquatch.applyReferralCode("BOBTESTERSON", forTenant: tenant, toUserID: userId, toAccountID: accountId, withToken: token,
    completionHandler: {(userInfo: AnyObject?, error: NSError?) in

        // First, make sure there is no error
        if error != nil {
            //handle errors
        }

        // Parse the referral code information returned in userInfo
        guard let reward = userInfo?["reward"] as? [String: AnyObject],
        let type = reward["type"] as? String else {
            return
        }

        // For a complete list of reward types and fields, please visit http://docs.referralsaasquatch.com/api/methods/#open_apply_code
        if type == "PCT_DISCOUNT" {
            guard let percent = reward["discountPercent"] as? Int else {
                return
            }
        }

        // Do something with the reward
    })

During your user's registration, you may want to look up a referral code they entered to check it's existance and get information about the associated reward. The call is very similar to applyReferralCode and returns the same reward information in userInfo. The tenant and referral code are the only required parameters, but if you make too many calls without a token you may get a 401: Unauthorized response. For a complete description of the available fields, visit the SaaSquatch docs.

Saasquatch.lookupReferralCode("BOBTESTERSON", forTenant: tenant, withToken: token,
    completionHandler: {(userInfo: AnyObject?, error: NSError?) in

        // Parse the reward as in applyReferralCode(_:forTenant:toUserID:toAccountID:withToken:completionHandler)

    })

Lookup who referred our new user

The last thing we would like to do is let our user know they have been referred successfully. Let's lookup the user that referred them so we can let our user know who they can thank. For this, we can use the userByReferralCode method like this:

Saasquatch.userByReferralCode("BOBTESTERSON", forTenant: tenant, withToken: token,
    completionHandler: {(userInfo: AnyObject?, error: NSError?) in

        // Always check the error
        if error != nil {
            //handle errors
        }

        // Parse the returned information
        guard let referrerFirstName = userInfo?["firstName"] as? String,
            let referrerLastInitial = userInfo?["lastInitial"] as? String,
            let referrerImageURL = userInfo?["imageUrl"] as? String else {
                return
        }

        // Now we can use this information to inform our user of their referral
    })

Great! We registered our new user with Referral SaaSquatch and successfully made a referral.

List Referrals

Let's add one more bit of functionality to our app to demonstrate listReferralsForTenant. Bob Testerson referred our new user, Claire Fraser, and we would like to show him a list of everyone he's referred (it's a lot). To do this, we call listReferralsForTenant.

This method looks up all the referrals for us, the tenant. The other required parameter is a token to authenticate the request. The remainder of the parameters are options for filtering this list. In this case, we want to list only the referrals where Bob is the referrer. We will pass in Bob's userId and accountId and parse the list returned in userInfo. For a description of the options for filtering, see the SaaSquatch docs.

Saasquatch.listReferralsForTenant(tenant, withToken: token, forReferringAccountID: bobsAccountId, forReferringUserID: bobsUserId, beforeDateReferralPaid: nil, beforeDateReferralEnded: nil, withReferredModerationStatus: nil, withReferrerModerationStatus: nil, withLimit: nil, withOffset: nil,
    completionHandler: {(userInfo: AnyObject?, error: NSError?) in

        // Check the error
        if (error != nil) {
            //handle errors
        }

        // Parse the list of referrals
        guard let referrals: NSArray = userInfo!["referrals"] as? NSArray else {
            return
        }

        for referral in referrals {

            guard let referredUser = referral["referredUser"] as? NSDictionary,
                let firstName = referredUser["firstName"] as? NSString,
                let referredReward = referral["referredReward"] as? NSDictionary,

                // In this case, we are giving out only percent discount rewards, so we know this field will exist
                let discountPercent = referredReward["discountPercent"] as? NSInteger else {
                    break
                }

            // Do something with the referral information
        }
    })

Done!

For a detailed description of the Saasquatch class and it's public methods, please visit the iOS SDK reference for Swift or Objective-C.

More information is available about the REST API Open Endpoints which underpin the SaaSquatch mobile SDK functionality.

The github repositories for the SaaSquatch iOS SDK framework for Swift and Objective-C apps are also available for reference.

For a working demo implementation, check out our Sample App