Passbook API

Use a passbook to store items like boarding passes, movie tickets, and gift cards. The Passbook API lets you scan your iPhone or iPod touch to check-in for a flight, get into a movie, redeem a coupon, and more.

IMPORTANT: Ensure that you have the iOS Passbook FFI imported into your project before you use Kony's Passbook API. The Passbook FFI is mandatory for the steps in this topic to work.

The Passbook API contains the following objects and related methods:

PassLibrary Object

Method	Description
`addPassWithCompletionCallback`	Presents UI to add pass.
`addPassesWithCompletionCallback`	Presents UI to add multiple passes.
`containsPass`	Returns whether the user’s pass library contains a pass.
`getPassWithTypeIdentifierAndSerialNumber`	The proximity value gives a general sense of the relative distance to the beacon.
`getPasses`	Returns the passes in the user’s pass library.
`removePass`	Removes the pass from the user’s pass library.
`replacePassWithPass`	Replaces a pass in the user’s pass library with the given pass.

You can add passes to a pass library using the addPassWithCompletionCallback or addPassesWithCompletionCallback functions. You can retrieve the available passes using the getPasses or getPassWithTypeIdentifierAndSerialNumber functions. Use the replacePassWithPass function to replace a pass with another pass, and the removePass function to remove a pass.

Pass Object

Method	Description
`getAuthenticationToken`	The token used to authenticate with the web service.
`getLocalizedDescription`	The localized description of the pass’s kind.
`getLocalizedName`	Use this property to provide accessibility information for a UI element that represents a pass, such as a cell in a table view.
`getLocalizedValueForKeyForDeviceLocale`	Returns the localized value for specified field of the pass.
`getOrganizationName`	The name of the organization that created the pass.
`getPassTypeIdentifier`	The pass’s type identifier.
`getPassURL`	The URL that opens the pass in the Passbook app.
`getSerialNumber`	A value that uniquely identifies the pass.
`getUserInfo`	Developer-specific custom data.

AddPassesViewController Object

Method	Description
`dismissAnimated`	Used to dismiss the view of add passes view controller.
`getLocalizedDescription`	The localized description of the pass’s kind.
`getLocalizedName`	Use this property to provide accessibility information for a UI element that represents a pass, such as a cell in a table view
`getLocalizedValueForKeyForDeviceLocale`	Returns the localized value for specified field of the pass.
`getOrganizationName`	The name of the organization that created the pass.
`getPassTypeIdentifier`	The pass’s type identifier.
`getPassURL`	The URL that opens the pass in the Passbook app.
`getSerialNumber`	A value that uniquely identifies the pass.
`getUserInfo`	Developer-specific custom data.

You can retrieve the authentication token for a pass using the getAuthenticationToken function. You can retrieve localized information about the pass using the getLocalizedDescription, getLocalizedName, or getLocalizedValueForKeyForDeviceLocale functions. Using the getOrganizationName function, you can retrieve the name of the organization that created the pass. You can retrieve information about the pass using getPassTypeIdentifier, getPassURL, or getSerialNumber functions, and retrieve information about the user using the getUserInfo function. You can dismiss the add passes view using the dismissAnimated function.

Here is an example for creating a isPassLibraryAvailable with callbacks:

var pass1 = new com.kony.isPassLibraryAvailable();

Input Parameters

None

Return Values

Boolean - True if available, false if not available.

Platform Availability

Available only on iOS.

Interacting with Passes

The KonyPassLibrary helps you interact with the Passes in iOS devices. All the Passes are contained within a PassLibrary.

The PassLibrary object represents the library of passes, and a Pass object represents an individual pass.

Determine the Availability of a Pass Library

The developer must check the availability of the iOS Pass library in the current device.

Use the following snippet to determine the availability of a pass library:


var isPassLibraryAvailable = com.kony.isPassLibraryAvailable();

var passLibrary = null;

if (isPassLibraryAvailable) {

   passLibrary = new com.kony.PassLibrary();

}

Check whether a Pass is in the Pass Library

Use the containsPass method to determine whether a pass is in the user pass library.


var aPass = new com.kony.Pass(path_to_pkpass_file);

var passLibrary = new com.kony.PassLibrary();

if (passLibrary.containsPass(aPass)) {
    // Pass is available in the pass library

}

Access Passes from the Pass Library

Use the getPasses method to get all the passes that a developer's application is entitled to access.

Read a Pass from the Pass Library

Use the getPassWithTypeIdentifierAndSerialNumber method to read a pass from pass library.

Developer can use methds such as getOrganizationName, getLocalizedDescription of Pass class to access information about the pass.

Use the getLocalizedValueForKeyForDeviceLocale method to access specific field data for a key.


pass = passLibrary.getPassWithTypeIdentifierAndSerialNumber(identifier, serialNumber);

var organizationName = pass.getOrganizationName();

var localizedDescription = pass.getLocalizedDescription();

Add a Pass to the Pass Library

AddPassesViewController is a view controller which can be used to display passes and let users add them to their pass library.

Create a pass with pass data file path, use a AddPassesViewController object to add passes to pass library.


function statusCallback(status) {
    if (status == "KonyPKAddPassesViewControllerFinished") {
        // view controller finished adding passes
    } else if (status == "KonyPKAddPassesViewControllerShown") {
        // view controller shown to add passes

    } else if (status == "KonyPKAddPassesViewControllerDismissed") {
        // view controller dismissed
    }

}

var aPass = new com.kony.Pass(path_to_pkpass_file);

var addpassesview = com.kony.AddPassesViewController([aPass],statusCallback);


addpassesview.presentAnimated(true);

Modify a Pass

Application can download a new pass(signed) from server and replace it in the pass library using replacePassWithPass method.


var newPass = new com.kony.Pass(path_to_new_pass);
var passLibrary = new com.kony.PassLibrary();
passLibrary.replacePassWithPass(newPass);

Remove a Pass from the Pass Library

Use the removePass method of PassLibrary class to remove a pass from pass library.


var pass = new com.kony.Pass(path_to_pass);
var passLibrary = new com.kony.PassLibrary();
passLibrary.removePass(pass);

Open a Pass in the Passbook application

Use getPassURL property to present the pass in Passbook.