iOS Mobile Browser Extension

iOS Safari Extension Documentation

Revisions:

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

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

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

6. Create a new Kindred Safari Extension

7. Update the name and description of your extension

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

8. Update the required logos

Update the logos found in /Resources/icons

9. 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].

10. 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")

11. Call to action (optional)

Once we track successful transactions for the user, 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)

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

12. 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.

13. 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

2. 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.

3. 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.
4. 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.

Customizations

1. Kindred Popup Customization
   you can modify the look and feel of our popups to suit your brand needs.

You can customise your popups by editing the above file which is located at/Resources/static/styles.css

--primary-color
This refers to the primary color used across the extension. Changing this color will have an effect on all the below popups and menus:

The safari menu toggle and "copy" button colors.

The Deal Available popup cta

The auto-coupon popups popup cta and savings amount text

Please note, that changing the color "--primary-color" property will change all instances of green in the above images to your desired color.

--Kmenu-activate-button-color
This refers to the activate deal button on the safari menu.
This can be seen on the images below:

pin-button-badge-color
This refers to the color of the pinned button badge that indicates the number of codes available

auto-coupons-progress-bar-color and the auto-coupons-progress-bar-background-color
These refer to both the color and the background color of the progress bar

button-border-radius
This refers to the border-radius of the cta buttons

checkout-page-button-gradient
This refers to the color of the tile on the checkout page when the pin is disabled

2. Customizing Images

   We have the ability to change certain images on the extension.
   You can change these images by adding your images inside the Resources/icons/images folder then editing the variables.js file located at Resources/static/js/variables.js with the path and name of your image.

   

   The images you have the ability to change are the ones below:

   apply_discounts_popup_image:

   

   “in_progress_popup_images”:

   

   “no_savings_popup_image”

   

   “no_deals_found_popup_image”

   

   “deal_activating_loading_animation_image”

   • For this image specifically if you want to use the default loader as in the image below you can leave the image path as an empty string
   

3. Customizing Text
   All text throughout the extension is customizable.
   Text can be changed using the variables.js file located at Resources/static/js/variables.js
   There is a translations object which allows for adding custom text, the only condition is that this exact object structure and key names need to be used as below. In the translations object you need to prefix the object with the language code as in the below file

en: {
    "contentApp": {
      "deals": {
        "activated": {
          "noCouponsBold": "Whoohoo!",
          "hasCouponsBold": "Coupons available at checkout!",
          "hasCouponsSmall": "We will plant trees with your purchase",
          "basic": "Deal Activated",
          "basicWithCoupons": "Deal Activated & Coupon copied",
          "noCouponsSmall": "We will plant trees with your purchase"
        },
        "activating": {
          "searchingForCoupons": "Searching for coupons"
        },
        "available": {
          "activateAll": "Always plant trees when I make a purchase",
          "activate": "I'd rather you only plant with this purchase",
          "noCodes": {
            "keepLooking": "We’ll keep looking...",
            "plantTrees": "Click to plant trees with your purchase"
          }
        },
        "postPurchase": {
          "line1": "Woohoo!",
          "line2": "Your recent purchase has contributed to planting trees",
          "cta": "Go to App",
          "o2": "Check out your trees planted in the O2 app"
        },
        "checkout": {
          "titleWithCode": "Copy discount codes below",
          "copy": "Copy",
          "copied": "Copied!"
        },
        "noDealsOrCoupons": {
          "plantTreesLine1": "We'll still plant trees if you make a purchase from this website!",
          "plantTreesLine2": "(Because we're awesome like that.)",
          "findMeCodes": "Find me coupon codes for next time!",
          "thanks": "Thanks! We’ve let the team know.",
          "letUsKnow": "Let us know you want coupons on this site",
          "keepLookingLine1": "We're always adding new coupon codes",
          "keepLookingLine2": "so please check back soon."
        },
        "revealCodes": "Click to reveal codes"
      }
    },
    "settings": {
      "automatic-deals": "Automatic deal activation",
      "automatic-deals-explainer": "This means that every time you browse through your favourite shops, we will find the best deals and these will be automatically activated.",
      "o2": {
        "automatic-deals": "Automatically reduce the impact of my purchases",
        "automatic-deals-explainer": "This means Kindred can collect savings from brands automatically and provide those savings to you in support of green projects to reduce the impact of your purchases. By turning this on you give Kindred permission to check for a deal every time you go to a website and automatically activate this."
      }
    },
    "store-deals": {
      "title": "Store Deals"
    },
    "deals": {
      "now-active": "is active",
      "activate": "Activate",
      "cashback": "Up to {{cashback}} cash back",
      "deal-lowered": "deal",
      "deal": "Deal",
      "cashback-lowered": "up to {{cashback}} cash back",
      "no-deals": "No deals found for {{domain}}. Try another store."
    },
    "coupon": {
      "copied": "Copied",
      "copy": "Copy"
    },
    "termsAndConditions": {
      "click": "Click here to view the T&C’s",
      "expanded": "T&C's: Coupons are subject to each stores T&C's so they may only work for specific items on the website, or if your basket meets a minimum order value. Apply codes to check if they are accepted."
    },
    "autocoupons": {
      "start": {
        "couponsFound": "{{total}} Coupons Found!",
        "wellTestThem": "We'll test them to find you the best deal.",
        "applyDiscounts": "Apply Discounts"
      },
      "inprogress": {
        "lookingForDiscounts": "We are busy testing coupon {{coupon}} of {{total}} ",
        "findingBestDeal": "Let's find you the best deal",
        "savings": "You've saved <0>{{currency}}{{formattedSavings}}</0> so far"
      },
      "continue": "Continue to checkout",
      "finished": {
        "totalSavings": "You have saved <0>{{currency}}{{formattedSavings}}!</0> ",
        "biggestSavingCoupon": "The biggest saving coupon:"
      },
      "failed": {
        "line1": "Coupon codes couldn’t be automatically applied.",
        "line2": "Try copying the discount codes directly to the discount code field at checkout."
      },
      "nosavings": {
        "line1": "You have the",
        "line2": "best price already!"
      },
      "automaticallyApplyDiscountsButton": "Apply Discounts",
      "notifications": {
        "inprogress": {
          "line1": "Looking for discount codes..."
        },
        "finished": {
          "line1": "Your discounts were applied",
          "line2": "Added more to your basket?",
          "button": "Apply discounts again"
        },
        "nosavings": {
          "line1": "No discount codes found",
          "button": "Try again"
        }
      }
    },
    "kmenu": {
      "couponCodes": "Coupon Codes",
      "applyDiscounts": "Apply all",
      "whoohoo": "Whoohoo!",
      "plantingTrees": "We are planting trees with your purchase.",
      "availableCodes": "{{codes}} Available",
      "codesExplainer": "If codes don’t pop up automatically at checkout, copy the codes below",
      "settings": {
        "title": "Settings",
        "autoCheckCoupons": "Auto check coupons",
        "autoCheckCouponsExplainer": "Automatically check for coupons and plant trees as I shop",
        "allowPinnedIcon": "Allow Pinned Icon",
        "allowPinnedIconExplainer": "Get coupons at the touch of a button while you browse"
      }
    }
  }

API Declaration

As of May 1, 2024 Apple requires all apps that make use of APIs that require reason to declare it on their apps privacy manifest. Below are steps to add/update your privacy manifest with APIs used by the Kindred Extension.

1. Open Your Project in Xcode:
   Launch Xcode and open your project.Choose File > New > File

   

2. Scroll down to the Resource section, and select App Privacy File template.

   

3. Click Next , and make sure the target is set to your project and the Kindred extension. Click create
   The file is named PrivacyInfo.xcprivacy this is the required file name for bundled privacy manifests.

   

4. Add NSPrivacyAccessedAPITypes Entry :
   Highlight an existing entry, then click the "+" button to add a new entry.
   Type NSPrivacyAccessedAPITypes or Privacy Accessed API Types , and it will be set as an Array.

   

5. Configure the API Type and Reasons:
   Expand NSPrivacyAccessedAPITypes and add a new Dictionary item inside it.
   In the Dictionary, add a key NSPrivacyAccessedAPIType with the value NSPrivacyAccessedAPICategoryUserDefaults or User Defaults. Add another key NSPrivacyAccessedAPITypeReasons as an Array.

   

6. Update the NSPrivacyAccessedAPITypeReasons array with the following values for Kindred extension usage. Inside this array, add the values CA92.1 and 1C8F.1 . Clean and build your project to apply the changes

   

XML Representation of the PrivacyInfo.xcprivacy

<key>NSPrivacyAccessedAPITypes</key>
<array>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
            <string>CA92.1</string> <!-- Local storage within the extension -->
            <string>1C8F.1</string> <!-- Shared preferences across the app group -->
        </array>
    </dict>
</array>

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