iOS Mobile Browser Extension

iOS Safari Extension Documentation

Revisions:

VersionDetailsDateAuthor
1.0Initial Release27/04/2022SB
1.5- Improvements for setting currency and region - Callback to the app when transactions are tracked - Overall improvements05/08/2022SB
1.6- introduced a feature flag for turning on/off cashback label on popups11/10/2022SB
1.7- Aligned cashback messaging with Android SDK
- Updated readme.io docs to include update instructions
31/10/2022SB
1.8- Added localisation for German, French, Spanish, Korean
- Added detection of Extension First Installation
20/01/2023SB
1.9- Introduced Automatic Coupons at the checkout
- Added analytics support (to be toggled on)
23/01/2023SB
1.9.1- Addition of Kindred License Agreement02/06/23EL

Prerequisites

  • You must have Xcode installed (Tested on version 13.0)
  • An existing iOS application

Getting Started

Follow these instructions to add the Kindred iOS Safari Extension to your existing iOS application.

For any questions or support with your integration, or to receive your API details, please contact [email protected]

  1. Down the Xcode Kindred Safari Extension template
  2. Navigate to your Xcode folder:
    Open new Finder window. Then go to Go -> Go to Folder and type~/Library/Developer/Xcode

Create a new folder called Templates

  1. Copy across the Kindred Safari Extension.xctemplate to your newly created folder

  1. Open your Xcode iOS project
  2. Select File -> New -> Target
    You should now see the Kindred Safari Extension under templates

  1. Create a new Kindred Safari Extension

  2. Update the name and description of your extension

You can update the name and description from the file /Resources/_locales/en/messages

  1. Update the required logos

Update the logos found in /Resources/icons

  1. Set your Kindred credentials

Open the info.plist of your extension, and set your Kindred credentials. Note, you need to set your CLIENT_ID, CLIENT_SECRET and SHARED_KEY.

To get your Kindred credentials, please contact [email protected].

  1. Setting the user ID (optional)

The default configuration gives each user a unique user ID. If you wish to provide your own user ID or a unique identifier for the user for analytic purposes, you can make the relevant updates on the `SafariWebExtensionHandler.swift.

Provide the SDK with you own unique ID as follows:

KindredSettings.shared.saveSetting(obj: userId, key: "KKUserId")
  1. Call to action (optional)

Once we track successful transactions for the user and they have earned some cashback, we present them with a popup that has a call to action back to the app. In order for this to function, you must provide us with the url scheme you have set for your app.

KindredSettings.shared.saveSetting(obj: "kindredsafariextensionsampleapp", key: DataKey.KKAppSchemeKey)
  1. Show cashback label feature flag (optional)

You can turn on/off the cashback label feature flag. Having it on means that when we detect a cashback deal, the user will be notified through the popups with text indicating how much cashback they would be earning. Having the feature off, means that there will not be any reference to cashback or cashback amount but instead, will reference a deal.


        KindredSettings.shared.saveSetting(obj: true, key: DataKey.KKShowCashbackLabelKey)
Feature flag off

Feature flag off

Feature flag on

Feature flag on

To learn more about URL scheme, please visit: https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app

  1. Detecting if the extension was installed

NOTE: You will need to follow the steps for enabling the App Groups in order to use this functionality.

One thing you may need to know is if your users have activated the extension. This is possible by using the following method:

KindredSettings.shared.IsExtensionFirstTimeInstall()

This will return either a true or false value.

Note: Due to the nature of the iOS Safari Extension, it is not possible to know whether the user has deactivated the extension. This method only indicates whether we have recognised if the extension was activated for the first time.

Troubleshooting: Whilst testing, if you notice that the value is retuning back false when you know it should return true, one thing to make sure is configured properly is the Apple App Group. In order for the Extension to communicate with the App, is through UserDefaults using the app groups. App Groups allow the extension and the app to create channel of shared data, and we use that to communicate between the extension and the app.

  1. Turning on analytics

If you would like to analytics tracking turned on, you can call self.setUseAnalytics(enabled: true) within the SafariWebExtensionHandler.swift file. This allows Kindred to track analytics on the following:

  • Extension installation and enabling
  • Latest activity
  • Deal activations
  • Conversions

NOTE: If you would like to opt in to analytics, you will also need to contact Kindred to ensure that your account is configured for analytics. Contact [email protected]

Verify the solution

You can verify the solution by running the app on the simulator.

  1. Open Safari

  2. Navigate to https://sdk.kindred.co/plugin-activation

  3. Follow the instructions in the screen

  4. visit your favourite brands

Try visiting Nike, Adidas or John Lewis

Activation Call-To-Action

On your onboarding journey, you can direct the users to a Kindred hosted page with instructions on how to activate the iOS mobile browser plugin.

The plugin activation page is: https://sdk.kindred.co/plugin-activation

If you would like to make use of our callback that redirects the user back to your app once they're done activating the plugin, you can pass a query parameter origin with the value of the URL scheme of your app.

https://sdk.kindred.co/plugin-activation?origin=YOUR_URL_SCHEME

For example, if your url scheme is kindred:// then you will use the link https://sdk.kindred.co/plugin-activation?origin=kindred

To learn more about URL scheme, please visit: https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app

Updating the iOS Safari Plugin

To update your iOS Safari plugin, follow these steps:

  1. Download the latest version of the iOS Safari Plugin
  2. Extract the zip files
  3. Open your finder (Mac) or file explorer (Windows) to view the content of your Safari Plugin from your App Solution
  4. Copy the following content of the new version over the content of your plugin files (replace)
    1. _locales
    2. asset-manifest.json
    3. favicon.ico
    4. icons
    5. index.html
    6. KindredSettings.swift
    7. KindredSWEHandler.swift
    8. manifest.json
    9. SafariWebExtensionHandler.swift
    10. static
  5. Note, the file TemplateInfo.plist is excluded from being copied. This file does not need updating
  6. Follow step 1 to 3 to make sure you have the latest version included in your Xcode templates

App Group Configuration

  1. You will now need to set up app groups within your Apple developer account.
    To create a new App Group, do the following:
  • Visit Apple's iOS Developer Centre, open your Account and log in.
  • Select Certificates, IDs & Profiles.
  • Under Identifiers select App Groups and click the + button to create a new group.
  • Enter a Name and an Identifier for the new group and click the Continue button:
  • Click the Register button to create the group and the Done to return to the list of registered App Groups
  1. Now, back in Xcode, go to the Project Navigator -> Select your applications target -> Head to the Signing and Capabilities tab -> Click the + button and search for groups. Add an App Group.

Important Note: Repeat this step for your Safari Extension target.

  1. Head to your application info.plist and add a key for AppGroupName with a string value matching the group name you created in step 1.
  2. Now head to the plugin extension info.plist and add a key for AppGroupName with the same string value as steps 1, 2 and 3.

License Agreement: https://event.kindred.co/licensing-terms-and-conditions