iOS SDK Quickstart Guide
An installation walkthrough for the SaaSquatch iOS SDK, including explanations of common usage cases, and code examples.
π Installation
The 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', '~> 2.0.0'
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.2.1'
end
Save and close the Podfile, then run $ pod install
.
π Including our Pod
Within your project's workspace (e.g. CocoapodsTest.xcworkspace
) you will find both your project and the Pod project contain the SaaSquatch SDK.
If your project is written in Swift, add this to the top of your files:
import saasquatch
If your project is written 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
With the SaaSquatch SDK you can create/update participants within your referral program, track users' referrals and rewards, fetch user information, and lookup referral codes and links. In this way, the SDK provides the flexibility to work directly with the data from your referral program and display it in your mobile app.
The following steps of this guide will cover creating/updating a user in SaaSquatch, and then connecting a referral. This process will be broken down in the following components:
- Create/update a user in SaaSquatch.
- Lookup Referrer info by referral code.
- Lookup information about referrals a user has made.
π Signing Requests
The SaaSquatch Mobile SDK is build on our Open Endpoints API functionality, and requests are signed with JWTs. More information about these API methods can be found in our Open Endpoints documentation.
π Create/Update a User
The SaaSquatch mobile SDK includes a userUpsert
method which can be used to create/update participants in your SaaSquatch project.
This method is helpful when programatically updating information about existing users within your program from within your app, as well as for registering new users who sign up from within your app.
Full details about the structure of the payload, and information that is returned, can be found in our API reference.
π Attribute Referral
The userUpsert
method can be used to attribute the Referred User's referral back to the correct Referrer.
This is accomplished by including the referral code of the Referrer as the code
field within the referredBy
object in the Refered User's user object.
Use the Branch SDK to retrieve the Referrer's referral code automatically. Learn more about our branch.io integration. Alternatievly, ask the Referred User to enter the referral code of their Referrer when they signup in your app.
In the following example the referral code JANEDOE
is applied to the Referred User to attribute their referral back to the correct Referrer.
π Convert Referral
The userUpsert
method can also be used to convert a referral.
This is accomplished by setting the isConverted
field within the referredBy
object in the Referred User's user object to true
.
π Example
User object:
// This is your tenant alias which identifies you with Referral SaaSquatch
let tenant = "acpiocfij942"
// Set the SaaSquatch account and user ID to a unique value you have for each participant in your system
let userId = "abc_123"
let accountId = "abc_123"
let referredBy: [String: AnyObject] = [
"code": "JANEDOE",
"isConverted": true]
let userInfo: [String: AnyObject] = [
"id": userId,
"accountId": accountId,
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"locale": "en_US",
"referralCode": "JOHNDOE",
"referredBy": referredBy]
Using the above user object, call the userUpsert
method:
// 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
})
The userUpsert
method includes a completionHandler
which runs after the async call returns. This completion handler is called with userInfo
and error
, and contains the returned user information or details about any errors (if any) that were encountered. If error
is nil then userInfo
will exist and vice versa.
In the following example the completion handler is used to parse the returned user data:
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
}
}
π Lookup the Referrer
Using the referral code retrieved from the branch deeplinking data you can lookup who the referrer is. This info can then be used to personalize the referral experience for the Referred Visitor (e.g. by including the Referrerβs name on the opening screen of your app).
The following example shows looking up the information of the Referrer associated with the referral code JANEDOE
:
Saasquatch.userByReferralCode("JANEDOE", 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
})
π List Referrals
As part of the referral experience within your app, it's recommended to include a list of the referrals that a user has made. This can help them track the progress of their pending referrals, and see how many rewards they have earned.
The listReferralsForTenant
method can be used to lookup a list of referrals made by a user in your program.
Further details about the structure of the payload, and the information that is returned by this method, can be found in the SaaSquatch
docs.
The following example details looking up the referrals that have been made by the user John Doe (accountId abc_123
, userId abc_123
). The method accepts John's userId and accountId, and returns the list of referrals in userInfo
.
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.