PepperHQ Developer

The PepperHQ Developer Hub

Hand crafted, customised and bespoke mobile experiences to suit your brand and needs.



Getting started with the iOS SDK

Getting Started

Step 1: Install the library

We publish our SDK as a static framework that you can copy directly into your app.

  1. First, request the iOS Framework from the team at Pepper.
  2. Unzip the file.
  3. In Xcode, with your project open, click on 'File' then 'Add files to "Project"...'.
  4. Select PepperSDK.framework and PepperSDK.bundle in the directory you just unzipped.
  5. Make sure 'Copy items if needed' is checked.
  6. Click 'Add'.
  7. In your project settings, go to the "Build Settings" tab, and make sure -lc++ -ObjC is present under "Other Linker Flags".

Additional required frameworks

  • Judopay payment provider framework available here
  • ImageIO
  • CoreMedia
  • CoreTelephony
  • CoreBluetooth
  • SystemConfiguration
  • AVFoundation

Step 2: Initializing SDK

The SDK is accessed via a singleton object. The first access of the singleton should provide a configuration dictionary, as detailed below.

[Pepper SDKWithConfiguration:@{"applicationId":@"YOUR_APPLICATION_ID"}]

This should initialize the SDK, with confirmation appearing in the Console.
Subsequent calls to the SDK use the following method.

[Pepper SDK]

Step 3: Typical user registration and login journey

In order to access SDK features, a user is required to register an account. This can be achieved through your own UI or via the FacebookSDK.

The phone number and password journey is as follows:

  1. Register with phone first name, last name, phone number and password, using type MOBILE
  2. Receive SMS with activation code
  3. Activate with phone number and activation code (automatically logged in on success)

The facebook journey is as follows:

  1. Call FacebookSDK to retrieve userId and token
  2. Register with facebook details and type FACEBOOK
  3. Login with facebook userId and token
[[Pepper SDK] registerWithDetails:success:failure]

An example of the details parameter

	"id":"01234 987654",

Details Properties

  • id : Phone number, email or Facebook userId
  • token : Password or Facebook token
  • credentials : Credential details
    • provider : MOBILE, EMAIL or FACEBOOK
    • firstName : User's first name
    • lastName : User's last name

In the case of facebook registration, successful registration means you can now login with these details.

In the case of a mobile number registration, you will also need to activate the account. Successful registration will have triggered an SMS to be sent to mobile with an activationCode.

[[Pepper SDK] activateWithDetails:success:failure]

An example of the details parameter

	"id":"01234 987654",

Details Properties

  • id : Phone number
  • token : SMS code

Successful activation automatically logs in the user. Subsequently you can choose to login and logout with:

[[Pepper SDK] loginWithIdentity:token:type:success:failure]
[[Pepper SDK] logoutWithSuccess:failure]

Once logged in you have access to various user details through convenience methods, in addition to all the SDK functionality.

Step 4: Suggested post-login actions

A typical first call after login is to retrieve the tenant locations.

[[Pepper SDK] getLocationsWithUserLocation:perPage:page:summary:bypassCache:success:failure]

Additional configuration options

The configuration dictionary allows you to setup the functionality of the SDK. Only one property, applicationId, is required to access the most fundamental features of the SDK. An example of such a configuration:


alternatively for STRIPE payments the payments object would be:


Configuration Properties

  • applicationId : This string will be provided by Pepper
  • beaconUUID : If beacons are being used for checkin functions, they must all use the same UUID
  • beaconMajors : Array of up to three beaconMajors, typically only one is needed unless some of your locations are in very close proximity to one another
  • payments : Payment provider details
    • provider : JUDOPAY or STRIPE
    • key : Key from payment provider
    • secret : Secret from payment provider (only applicable to JUDOPAY)
    • useLiveEnvironment : Determines which environment on the providers' platform to target. Your respective live or sandbox keys should be used in line with this value.

Core concepts

User account model

A user account on pepper is surfaced through the current logged in session. These sessions do not expire on the device, however you may choose to
enforce login or logout as you see fit for your application. Bear in mind that when logged out, functionality such as background checkins will not function.

Typically, once registered, a user will login once and not need to repeat this action. When logged in, the SDK makes user details available through a variety of convenience methods to allow your UI to reflect the current user balance, loyalty points etc.. When actions are performed that will change the user's account, ie a purchase, you should make a call to get the updated user object and base UI changes on this data.

[[Pepper SDK] refreshUser]


[[Pepper SDK] getUserBypassingCache:success:failure]


A user makes payments via their account balance. This balance is topped up from the user's payment card. It is also possible to enable auto topup on a user's account, which will automatically add £10 to the user's balance when their account balance falls below £10. This topup will occur on the platform and a push notification is sent to the user's device. Topups are included in the user's events.

[[Pepper SDK] currentUserBalance]


In order to have purchases made against their account, a user needs to either checkin to a location or place a pre-order if the location supports it. Checkins can either be manual or automatic. If a given location is added to a user's favourite locations, they will automatically be checked in when entering its proximity, either via beacons or geolocation. This does not require application code, the SDK will attempt to checkin for you.

There is also the option to checkin manually

[[Pepper SDK] checkinWithLocationId:type:trigger:success:failure]

You may wish to limit the ability to check in based on the location of the user. The SDK offers a method to perform this check with a completion block containing a boolean for inRange, or an error describing potential reasons for not being able to obtain this information, for example insufficient app permissions or location services being disabled.

[[Pepper SDK] locationManager] isWithinRangeOfLocation:completion]


Most of the method for retrieving data from the platform allow you to specify a bypassCache parameter. Setting this to YES will always attempt to get the latest version from the platform. Setting it to NO will route requests through Apple's caching mechanism in iOS, whereby if no network is available a cached version is returned, or if the resource has updated via the use of ETags. In the case of critical requests such as refreshing the user object it is recommended to bypass the cache, in addition to distinct refresh commands such as a pull to refresh action on the UI.

Updated about 21 hours ago


Getting started with the iOS SDK

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.