Granify Class Reference


                    
                    
                    activateGranify(with:)

Activates the Granify SDK and initiates communication with Granify’s servers.

Placement

This function must be called on app launch before any other method on this API (excepting subscription and registration methods) to allow the SDK to intialize itself with the provided site information.

See Configuring Granify for details on how to prepare the GranifyConfiguration object.

Declaration

Swift

@objc
public class func activateGranify(with config: GranifyConfiguration) throws

Parameters


                                config

The GranifyConfiguration object which contains all SDK configuration


                    
                    
                    subscribeGroupAssigned(handler:)

Registers a callback to notify you when a matching group has been assigned.

In most cases, this handler is expected to send the group assignment information to your analytics. This group assignment metric tracks whether the current shopper is eligible to be shown a message (“Granify” group), or not (“baseline” group).

Expect your handler to be invoked by Granify on startup, and when a new session is started (eg: after a lengthy period of inactivity).

Placement

This function can be called at any time, but it is most effective when called prior to activateGranify(...) to ensure a handler is registered in advance of the group assignment taking place.

Usage

The group that your handler receives when invoked is the exact group that should be reported in your analytics. IMPORTANT: ABSOLUTELY NO CHANGES ARE ALLOWED TO BE PERFORMED ON THE GROUP WHEN REPORTING IN YOUR ANALYTICS.

Declaration

Swift

@objc
public class func subscribeGroupAssigned(handler: @escaping (MatchingGroup) -> Void)

Parameters


                                handler

The function to be called for notification of a matching group assignment


                    
                    
                    subscribeMessageShown(handler:)

Registers a callback to notify you when a message is (or could have been) shown.

In most cases, this handler is expected to send the display status information to your analytics. The message shown metric tracks when our engine decides to show a message to a shopper. Messages may be shown or notShown depending on the shopper’s group assignment (granify vs. baseline, respectively).

Expect your handler to be invoked by Granify at any time, when our engine decides to show a message to a shopper.

Your handler will be invoked on the main process thread.

Placement

This function can be called at any time, but it is most effective when called prior to activateGranify(...) to ensure a handler is registered in advance of any messages being shown.

Declaration

Swift

@objc
public class func subscribeMessageShown(handler: @escaping (DisplayStatus) -> Void)

Parameters


                                handler

The function to be called for notification of a message display


                    
                    
                    registerGroupAssignment(provider:)

Register a handler for providing group assignments when a new session is created.

In most cases, Granify controls matching group assignments, but arrangements can be made with Granify to control group assignments via this handler instead. Allowed group values for your site may be a subset of those in the MatchingGroup enumeration, so work with your Account Manager to determine how to use this function for your specific needs.

Expect your handler to be invoked by Granify any time a request is made that may result in a new session. This will happen after the first trackPageView(...) request is made (starting traffic to the server) and at arbitrary later points when starting a new session after expiry.

Note that an invocation of this callback does not necessarily indicate that a new session will start. In some cases, the SDK may expect the session to be expired even though it is still active on the server. For example, rebooting the application will clear all local state causing the SDK to assume a new session is needed (thereby invoking this handler) even though the server can recover the existing session for the shopper. Use subscribeGroupAssigned(...) for reliable notifications of group assignments for new sessions.

Important

No guarantees are made about which thread may invoke your provider callback. The main process thread or a different worker thread may be used.

Placement

When in use, this function must be called prior to activateGranify(...) on application launch.

Declaration

Swift

@objc
public class func registerGroupAssignment(provider: @escaping () -> MatchingGroup) throws

Parameters


                                provider

The callback function that provides the MatchingGroup for the session being initialized


                    
                    
                    setShopperId(shopperId:)

Notifies Granify of the current customer’s unique identifier.

This should be the same identifier you use in your store for your customers. It should not change if the same customer returns. If the shopper cannot be uniquely identified, this function should not be called.

See Privacy and Data Protection for details on what kinds of information cannot be used for shopper IDs, but please, no email addresses.

Placement

This function should be called as soon as the shopper’s identifier is known. This may be:

On application launch
After the shopper signs in to their account

Declaration

Swift

@objc
public class func setShopperId(shopperId: String) throws

Parameters


                                shopperId

The unique identifier for the customer from your internal systems. This should remain the same for the customer on subsequent returns.


                    
                    
                    setChildSiteId(childSiteId:)

Notifies Granify that the child site has changed.

In cases where a client has an app that uses multiple child sites (multiple brands), use this method when the shopper switches from one brand to another.

See Multiple Brands In One App for details on when to use Child Site IDs.

Placement

This function should be called as soon as the child site (brand) in the app changes from the child site initially set in configuration, as well as any subsequent changes. If the brand changes because a new page is loaded, call this method immediately after the Granify.trackPageView(...) method, before Granify.trackProduct(...) or any other Granify call.

Declaration

Swift

@objc
public class func setChildSiteId(childSiteId: SiteIdentifier?) throws

Parameters


                                childSiteId

The site identifier for the child site. This should be Granify’s identifier, which will be provided to you.


                    
                    
                    trackPageView(pageType:parentView:mainScrollView:getInsets:)

Tracks any changes to the active “page” or view that is displayed to the user in the application.

It is important to keep Granify notified about the current page and the shopper’s navigation through the app so our engine can make appropriate decisions about what messages should be shown to which shoppers for maximum impact. This includes tracking what the user is currently viewing on the page via the use of scroll distance metrics which are inferred from the main UIScrollView for the page.

Warning

Deprecated. Use:

trackPageView(pageIdentifier: PageIdentifier, parentView: UIView?, mainScrollView: UIScrollView?, getInsets: () -> UIEdgeInsets)

See Tracking Pages for more details.

Placement

This function should be called:

On application launch
On application resume from background
Each time a page navigation occurs (ensure to place it inside the viewDidAppear() View Controller callback)

Declaration

Swift

@available(*, deprecated, message: "Use: trackPageView(pageIdentifier: PageIdentifier, mainScrollView: UIScrollView?, getInsets: (﹚ -> UIEdgeInsets﹚")
@objc
public class func trackPageView(pageType: PageType, parentView: UIView? = nil, mainScrollView: UIScrollView? = nil, getInsets: @escaping () -> UIEdgeInsets) throws

Parameters

`pageType`	The page type of the current page
`mainScrollView`	The main UIScrollView object of the current page (if the page is scrollable) Since 2.0.0
`getInsets`	A callback method that returns the insets within which a slider can be displayed. When called, provide insets from the screen edges representing areas that must not be occluded for the current page layout and orientation. Since 4.0.0
`parentView`	The superview containing all the subviews on the current page. This parameter must be passed in if inlines are desired to be displayed on that page Since 6.0.0


                    
                    
                    trackPageView(pageIdentifier:parentView:mainScrollView:getInsets:)

Tracks any changes to the active “page” or view that is displayed to the user in the application.

It is important to keep Granify notified about the current page and the shopper’s navigation through the app so our engine can make appropriate decisions about what messages should be shown to which shoppers for maximum impact. This includes tracking what the user is currently viewing on the page via the use of scroll distance metrics which are inferred from the main UIScrollView for the page.

See Tracking Pages for more details.

Placement

This function should be called:

On application launch
On application resume from background
Each time a page navigation occurs (ensure to place it inside the viewDidAppear() View Controller callback)

Since

6.2.0

Declaration

Swift

@objc
public class func trackPageView(pageIdentifier: PageIdentifier, parentView: UIView? = nil, mainScrollView: UIScrollView? = nil, getInsets: @escaping () -> UIEdgeInsets) throws

Parameters

`pageIdentifier`	Contains information about the page’s type and unique path.
`mainScrollView`	The main UIScrollView object of the current page (if the page is scrollable)
`getInsets`	A callback method that returns the insets within which a slider can be displayed. When called, provide insets from the screen edges representing areas that must not be occluded for the current page layout and orientation.
`parentView`	The superview containing all the subviews on the current page. This parameter must be passed in if inlines are desired to be displayed on that page


                    
                    
                    trackProduct(products:currentProductCarterCallback:)

Notifies Granify about the products available on a product page.

Supplied product information is cached in memory and may be used for the display of messages at a later point in time. All product variations (i.e. skus) on a page must be provided. For example, if a shirt has different colors and sizes, the product list provided must include an entry for every combination of shirt color and size.

See Tracking Products for more details.

Placement

This function must be called after trackPageView(...) when a product page is loaded:

On application launch to a product page (e.g. via deep linking)
On application resume from background (when resuming to a product page)
From a navigation action leading to a product page

Declaration

Swift

@objc
public class func trackProduct(products: [Product], currentProductCarterCallback: @escaping CurrentProductCarterCallback) throws

Parameters

`products`	The list of all products featured on the product page
`currentProductCarterCallback`	A handler that adds the current product to the cart


                    
                    
                    setCurrentProduct(sku:productId:)

Notifies Granify which specific product on a product page is currently selected.

See Tracking Products for more details.

Placement

This function must be called immediately after trackProduct(...), and when the focused item is changed on a product page. This includes:

On application launch to a product page (call with the default selected product sku)
On application resume from background to a product page (call with the selected product sku when the view loads)
From a navigation action leading to a product page (call with the default selected product sku)
User action that changes the selected product sku on a product page

Declaration

Swift

@objc
public class func setCurrentProduct(sku: String, productId: String) throws

Parameters

`sku`	The SKU of the currently selected product. Must match the sku field in one of the products called in `trackProduct(...)`
`productId`	The parent ID of the product.


                    
                    
                    trackCart(items:)

Notifies Granify of the contents of the shopper’s cart.

All cart information is required (rather than partial changesets) to sync the customer’s cart with Granify. Ensuring that this is kept up to date is crucial to ensure cart-related campaigns work.

See Tracking Products for more details.

Placement

This function should be called:

On initial app launch
After there is any change made to the cart. This includes:
- After a purchase is completed (to clear the cart), including through the use of a “Buy It Now” or other express purchase button
- Item removal
- Cart item quantity changes
- Updated cart information from a server response (e.g. from shopping performed on the same user account on a different device)

Note

This method should never be called in the same session with trackCartChange. The two methods are intended for mutually exclusive circumstances; you should never need to call both in the same app. See Which Cart Tracking Method Should I Use? for more details.

Declaration

Swift

@objc
public class func trackCart(items: [Product : Int]) throws

Parameters


                                items

A dictionary containing carted products as keys and corresponding cart quantities as values


                    
                    
                    trackCartChange(add:quantity:)

Notifies Granify that an item has been added to the cart, or that the quantity of an item already in the cart has been increased.

This method requires only information about the change itself. It does not require the complete cart details.

See Tracking Products for more details.

Placement

This function should be called whenever an additive change is known. The function should be called immediately. This function should not be called on app launch, or any time other than when an actual change happens in the cart.

Note

This method should never be called in the same session with trackCart. The two methods are intended for mutually exclusive circumstances; you should never need to call both in the same app. See Which Cart Tracking Method Should I Use? for more details.

Since

5.5.0

Declaration

Swift

@objc
public class func trackCartChange(add product: Product, quantity: Int) throws

Parameters

`add`	A `Product` object representing the whole product being added / incremented. This method does not differentiate between adding and incrementing, so we always require the whole product.
`quantity`	The number of items to add to the cart. This should describe the change, and not the final amount in the cart. So, if the cart already has 3 items, and this method is called with a quantity of 2, the cart will end up with a quantity of 5.


                    
                    
                    trackCartChange(remove:quantity:)

Notifies Granify that an item has been removed from the cart, or that the quantity of an item already in the cart has been decreased.

This method requires only information about the change itself. It does not require the complete cart details.

See Tracking Products for more details.

Placement

This function should be called whenever a subtractive change is known. The function should be called immediately. This function should not be called on app launch, or any time other than when an actual change happens in the cart.

Note

This method should never be called in the same session with trackCart. The two methods are intended for mutually exclusive circumstances; you should never need to call both in the same app. See Which Cart Tracking Method Should I Use? for more details.

Since

5.5.0

Declaration

Swift

@objc
public class func trackCartChange(remove sku: String, quantity: Int) throws

Parameters


                                remove

The sku of the product in the cart.


                                quantity

The number of items to remove from the cart. This should describe the change, and not the final amount in the cart. So, if the cart already has 3 items, and this method is called with a quantity of 2, the cart will end up with a quantity of 1. If this value is greater than or equal to the current quantity in the cart, the item will be removed completely. If you do not know how many items are currently in the cart, use a very high number that you are sure is more than the quantity in the cart.


                    
                    
                    trackOrder(details:)

Notifies Granify about completed purchases.

Placement

Call this function after the order has been finalized and paid (for example, when the receipt page is displayed). The data provided to Granify must match the data provided to your analytics.

Declaration

Swift

@objc
public class func trackOrder(details: Order) throws

Parameters


                                details

An object containing the details of the completed order


                    
                    
                    trackWishList(name:contents:)

Notifies Granify of the contents of the shopper’s wish list.

This method can be called multiple times for different lists you wish to track. Please ensure that you use a unique name for each list tracked (e.g. “Saved for Later”, “Christmas”, etc.) per user.

Placement

This function should be called:

On initial app launch
After there is any change made to the wish list
- Updated wish list information from a server response (e.g. from shopping performed on the same user account on a different device)

Declaration

Swift

@objc
public class func trackWishList(name: String, contents: [WishListItem]) throws

Parameters

`name`	The name of the wish list being tracked
`contents`	The contents of the wish list


                    
                    
                    trackUserData(userData:)

Notifies Granify of any information you want to remember and persist for any user of the device on which it is running. It will persist across pages within the current user session.

Placement

Call this method whenever the information about the user you’d like to store has changed.

Since

6.10.0

Declaration

Swift

@objc
public class func trackUserData(userData: String) throws

Parameters

`userData`	An escaped JSON string with key-value pairs to be tracked. Only Strings, Integers, Booleans, and Arrays of each of those three types are supported. Nested objects and null are not supported values. Keys must only include alphanumeric strings that are separated by underscores.
`Example`	`let exampleUserData = """ {\ \"example_string\": \"Example String\",\ \"example_bool\": true,\ \"example_int\": 1,\ \"example_string_array\":[\"example_1\",\"example_2\"],\ \"example_bool_array\":[true,false],\ \"example_int_array\":[1,2,3,4]\ }\ """ try Granify.trackUserData(userData: exampleUserData)`


                    
                    
                    showConcept(conceptId:)

Requests that Granify show a specified concept (which we now call a campaign) within this session.

Once requested the campaign will be shown at the next available opportunity. As concepts are designed with various limitation around their presentation, (e.g. only showing on a product page), the campaign may not appear immediately after this call is made.

This method is not intended for regular use and should not be called during regular customer shopping sessions. It is a business review tool that allows seeing what a given Granify campaign will look like within your application so that any desired changes can be requested of the Granify team. Granify strongly recommends creating an easy way for trusted users to trigger this function to simplify previewing and testing of new concepts as they become available.

The id strings used to request concepts, can be obtained through your Account Manager.

See Testing for more details.

Placement

This function can be called:

Any time after activateGranify(...) has been called

Since

2.0.0

Declaration

Swift

@objc
public class func showConcept(conceptId: String) throws

Parameters


                                conceptId

The id of the concept to display


                    
                    
                    setRestrictionState(to:)

Tells Granify to enter/exit a restricted state, during which no campaign can appear to the shopper. Note that this does not apply to inline campaigns, which will not be hidden while in a restricted state.

If your app has other popups, modals, or there are any times when you do not want a campaign to pop up, you can set the restricted state. When this state is on (.restricted), no campaigns will be shown. Switch it off to resume normal programming.

For example, if you have a promotional message that pops up when a shopper logs in, you might set the restricted state on while that popup is open, and then set if off again once the popup has been removed.

Please remember to always switch the restricted state off when you no longer require it.

The initial state of the SDK is RestrictionState.unrestricted upon activation.

Placement

This function should be called:

when entering a situation where a campaign should not be shown
when exiting a situation where a campaign should not be shown

Since

4.0.0

Declaration

Swift

@objc
public class func setRestrictionState(to restrictionState: RestrictionState) throws

Parameters


                                restrictionState

a RestrictionState value indicating whether a campaign can be shown


                    
                    
                    getCurrentState()

Generates an executable JavaScript script that will pass the current Granify state to an embedded webview that is running a page that uses the Granify JavaScript SDK.

If your app is a hybrid app, such that some of the app runs natively, and other parts run as web pages in webviews, it is necessary for Granify to pass state from the app to the webview whenever the app passes control from the app to the webview.

In such a case, call this method to receive a JavaScript snippet that will pass the current app state into the JavaScript Granify SDK running in the webview. This script should be executed before the JavaScript Granify SDK makes its first request to the Granify backend servers (which happens pretty soon after load). It is safe to load this script before the JavaScript Granify SDK has loaded. We recommend passing the script as soon as the webview finishes loading.

The internal state of the App Granify SDK changes with every product viewed, and the JavaScript Granify SDK needs the most up-to-date state to operate optimally. This means that the state must be passed again every time a new page loads into the webview - once for each time the JavaScript SDK loads.

Note

We do not currently support passing state from the webview to the app. This is planned for a future release, but for the time being, we can only support one-way transitions. This is appropriate if the app hosts its cart and checkout in a webview, but everything else in the app.

Placement

This function should be called:

when passing control from the app to a webview
must be called each time a new page loads inside the webview.

Since

5.1.0

Declaration

Swift

@objc
public class func getCurrentState() throws -> String


                    
                    
                    overrideGranifyInlineView(label:)

Specifies a GranifyInlineView location in which to display inline widgets for testing purposes.

Placement

Call this function when a user has manually entered an override string into a debug menu

Since

6.0.0

Declaration

Swift

@objc
public class func overrideGranifyInlineView(label: String) throws

Parameters


                                label

A JSON object specifying the details of a GranifyInlineViewLabel:

Example: {"name": <GranifyInlineViewLabel.name>, "product_id"(optional): <GranifyInlineViewLabel.productId>, "sku"(optional): <GranifyInlineViewLabel.sku>}