iOS Mobile Browser Extension
iOS Safari Extension Documentation
Revisions:
Version | Details | Date | Author |
---|---|---|---|
1.0 | Initial Release | 27/04/2022 | SB |
1.5 | - Improvements for setting currency and region - Callback to the app when transactions are tracked - Overall improvements | 05/08/2022 | SB |
1.6 | - introduced a feature flag for turning on/off cashback label on popups | 11/10/2022 | SB |
1.7 | - Aligned cashback messaging with Android SDK - Updated readme.io docs to include update instructions | 31/10/2022 | SB |
1.8 | - Added localisation for German, French, Spanish, Korean - Added detection of Extension First Installation | 20/01/2023 | SB |
1.9 | - Introduced Automatic Coupons at the checkout - Added analytics support (to be toggled on) | 23/01/2023 | SB |
1.9.1 | - Addition of Kindred License Agreement | 02/06/23 | EL |
1.9.5 | - Improvements and Optimisations | 09/06/23 | AT |
1.9.6 | - Improvements and Optimisations | 03/07/23 | AT |
1.9.7 | - Improvements and Optimisations | 10/07/23 | AT |
1.9.8 | - Added localisation for German, French, Spanish, Korean, Arabic, Hindi, Indonesian, Italian, Japanese, Polish, Portuguese, Russian, Thai, Turkish, Vietnamese, Chinese Simplified, Chinese traditional | 01/08/23 | AT |
2.0.0 | - Popup Redesign/ K-Menu - Popup Customisations - Coupons on-Demand via K-Menu - Auto Coupons - Post Purchase Notification with analytics - Translation updates for all supported languages - Optional feature flag for capturing user device ID as the user ID | 24/11/23 | AT |
2.0.1 | - Multi-domain handling - Improvements and Optimisations | 06/02/24 | AT |
2.0.2 | - Bug Fixes & Improvements | 16/02/24 | AT |
2.0.3 | - Bug Fixes & Improvements | 23/02/24 | AT |
2.0.4 | - Improvements and Optimisations | 29/02/24 | AT |
2.0.5 | - Auto coupons improvements - Bug Fixes & improvements | 23/04/24 | AT |
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]
- Down the Xcode Kindred Safari Extension template
- 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
- Copy across the
Kindred Safari Extension.xctemplate
to your newly created folder
- Open your Xcode iOS project
- Select File -> New -> Target
You should now see the Kindred Safari Extension under templates
-
Create a new Kindred Safari Extension
-
Update the name and description of your extension
You can update the name and description from the file /Resources/_locales/en/messages
- Update the required logos
Update the logos found in /Resources/icons
- 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].
-
Configure the minimum IOS deployment version.
This is the minimum IOS version the extension would work on.
To set this follow the steps below:-
Open your project in Xcode
-
Click on your application in the top left corner under the project files tab.
-
Select the extension under targets
-
Select the General tab
-
You should see a section called "Minimum Deployments", please select the appropriate version from the dropdown.
-
-
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")
-
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
- 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.
- Turning on analytics
If you would like to analytics tracking turned on, you can callself.setUseAnalytics(enabled: true)
within theSafariWebExtensionHandler.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.
-
Open Safari
-
Navigate to https://sdk.kindred.co/plugin-activation
-
Follow the instructions in the screen
-
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:
- Download the latest version of the iOS Safari Plugin
- Extract the zip files
- Open your finder (Mac) or file explorer (Windows) to view the content of your Safari Plugin from your App Solution
- Copy the following content of the new version over the content of your plugin files (replace)
- _locales
- asset-manifest.json
- favicon.ico
- icons
- index.html
- KindredSettings.swift
- KindredSWEHandler.swift
- manifest.json
- SafariWebExtensionHandler.swift
- static
- Note, the file
TemplateInfo.plist
is excluded from being copied. This file does not need updating - Follow step 1 to 3 to make sure you have the latest version included in your Xcode templates
App Group Configuration
- 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
- 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.
- 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.
- 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
- 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
-
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
-
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, the easiest way to do this would be to copy the entire object below and change the fields you need. To add any customized text for any other additional languages, please add additional objects for each language. E.g en: {}, de: {}
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.
-
Open Your Project in Xcode:
Launch Xcode and open your project.Choose File > New > File -
Scroll down to the Resource section, and select App Privacy File template.
-
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. -
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. -
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. -
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
Updated 25 days ago