iOS Keyboard SDK

iOS Keyboard SDK Documentation

Revisions:

Prerequisites

• Your application should be set up to use Cocoapods https://cocoapods.org
• You will require an active Apple developer account with signing capabilities

Getting Started

Follow these instructions to add the Kindred SDK to an existing iOS application.

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

1. We need to add a keyboard target to your app. Within Xcode, select File -> New -> Target and add a Custom Keyboard Extension and give your Extension a name.

2. Add the KindredSDK to your podfile.

source 'https://github.com/kindred-app/Specs.git'

target 'your_app_name' do
    pod 'KindredSDK', '2.0.10'
end

target 'your_keyboard_target' do
    pod 'KindredSDK', '2.0.10'
end

3. In terminal, navigate to your project folder and run: -
   pod install

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

5. 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 Keyboard Extension target.

6. Head to your application info.plist and add a key for AppGroupName with a string value matching the group name you created in step 4.

7. Now head to the keyboard extension info.plist and add a key for AppGroupName with the same string value as steps 4, 5 and 6.

8. Still within your keyboard extension info.plist file, now add a dictionary key named KindredKeyboard with 5 string values named, AuthClientId, AuthClientSecret, AuthSharedKey, BaseApiUrl, CDNUrl. This should look like the following: -
   Note: Contact [email protected] to acquire your credentials.

<key>KindredKeyboard</key>
<dict>
<key>AuthClientId</key>
<string>YOUR_AUTH_CLIENT_ID</string>
<key>AuthClientSecret</key>
<string>YOUR_CLIENT_SECRET</string>
<key>AuthSharedKey</key>
<string>YOUR_SHARED_KEY </string>
<key>BaseApiUrl</key>
<string>https://api-partners.kindred.co</string>
<key>CDNUrl</key>
<string>https://cdn.kindred.co</string>
</dict>

Note: Still within the keyboard extension info.plist, expand NSExtensionAttributes and make sure RequestsOpenAccess value is set to 1.

Note: This is important to grant keyboard access.

9. Within the extension KeyboardViewController, replace all existing code with the following: -

import UIKit
import KindredSDK

class KeyboardViewController: KindredViewController {
    convenience init() {
        self.init(nibName:nil, bundle:nil)
        self.setUserId(userId: "YOUR_USER_ID")
    }
    
    override func configureKeyboard() -> CustomerKeyboardConfiguration {
        return CustomerKeyboardConfiguration(
                display: KeyboardDisplayConfiguration(
                cashbackLabel: KeyboardDisplayConfiguration.cashbackLabelType(
                type: KeyboardDisplayConfiguration.CashbackLabel.CASHBACK),
                showWithdrawal: true
            ),
            user: UserConfiguration(userCountry: "UK", userCurrency: "GBP")
        )
    }
}

Note: The setUserId function simply sets a value in UserDefaults which can be used later, you can also set this value in your application by saving the value to UserDefaults using the key KKUserId. Example below: -

let defaults = UserDefaults.standard
defaults.setValue("YOUR_USER_ID", forKey: "KKUserId")

Note: replace YOUR_USER_ID with your user ID value

10. At this point we have set up the Kindred keyboard however, to add the logo we need to create an xcassets folder within your keyboard extension.

11. Select the keyboard extension within Xcode -> Right Click -> New file -> Asset Catalogue, name the folder images.

12. Within the images.xcassets folder we need to add 2 image assets named LogoActive and LogoInactive. These should both contain images assets for 1x, 2x & 3x respectively. E.g. -

13. We now need to add fonts to the keyboard target. Right click your keyboard target -> New group -> Call the folder fonts

14. Download the font from flicon.ttf

15. Drag the flicon.ttf font into the newly created font folder and make sure to check “copy items if needed” then click Finish.

NOTE: Within Xcode file explorer, select the font you just added then on the right hand column in Xcode make sure to select your keyboard target for the font (see below)

16. Inside your keyboard target info.plist add a key for “Fonts provided by application” with a value of “flicon.ttf” It should look like the following:

17. If you now close Xcode and head to your application project folder and open the xcworkspace you should now be able to run the keyboard project.

18. Remember to enable the keyboard and allow permissions in the iOS settings app.
    Settings -> General -> Keyboard -> Keyboards -> Add New Keyboard

Settings -> General -> Keyboard -> Keyboards -> YourKeyboard -> Allow Full Access

Note: To test deals you will need to use a browser.

Keyboard Settings Bundle

Summary

All Settings Reference

Setup

To add a Settings Bundle to your application you will need to action the following steps: -

1. Within Xcode Project navigator, select your application -> Right Click -> New File -> Select Settings Bundle. Leave the default name of “Settings”

2. Once you have added the settings bundle to your project you will see a new bundle containing a en.Iproj folder and a root.plist file.

3. Right click the root.plist file and select Open As -> Source Code

4. Replace the existing contents of the file with the following xml: -

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>ApplicationGroupContainerIdentifier</key>
<string>group.com.your_group_string</string>
<key>StringsTable</key>
<string>Root</string>
<key>PreferenceSpecifiers</key>
<array>
<dict>
<key>Type</key>
<string>PSGroupSpecifier</string>
<key>FooterText</key>
<string>There&apos;s only 3 steps to start using the Keyboard
1. Select &quot;Keyboards&quot;
2. Turn on &quot;Kindred Keyboard&quot;
3. Turn on &quot;Allow Full Access&quot;

*If &quot;Keyboards&quot; does not appear on this screen:
- If you have an iPhone 8 or earlier:
Please double-click the Home button, swipe up the
&quot;Settings&quot; and reopen &quot;Settings&quot; again. Then repeat the
operations above.
- If you have an iPhone X or later:
Please swipe up from the bottom to the middle of your
screen and swipe up the &quot;Settings&quot;. Reopen &quot;Settings&quot;
again and then repeat the operations above.</string>
</dict>
<dict>
<key>Type</key>
<string>PSGroupSpecifier</string>
<key>Title</key>
<string>Keyboard Settings</string>
</dict>
<dict>
<key>TrueValue</key>
<true/>
<key>FalseValue</key>
<false/>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Auto Correction</string>
<key>Key</key>
<string>com.kindred.setting.userAutoCorrection</string>
</dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Auto Capitalization</string>
<key>Key</key>
<string>com.kindred.setting.userAutoCapitalization</string>
</dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Double Tap Period</string>
<key>Key</key>
<string>com.kindred.setting.doubleTapPeriods</string>
</dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Show Word Predictions</string>
<key>Key</key>
<string>com.kindred.setting.showWordPredictions</string>
</dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Autolearn From User</string>
<key>Key</key>
<string>com.kindred.settings.autolearnFromUser</string>
</dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Emoji Suggestion</string>
<key>Key</key>
<string>com.kindred.settings.emojiSuggestion</string>
</dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Emoji Prediction</string>
<key>Key</key>
<string>com.kindred.settings.emojiPrediction</string>
</dict>
        <dict>
            <key>DefaultValue</key>
            <true/>
            <key>Type</key>
            <string>PSToggleSwitchSpecifier</string>
            <key>Title</key>
            <string>Typing Sounds</string>
            <key>Key</key>
            <string>com.kindred.settings.typingSounds</string>
        </dict>
<dict>
<key>DefaultValue</key>
<true/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Swipe Typing</string>
<key>Key</key>
<string>com.kindred.settings.swipetyping</string>
</dict>
<dict>
<key>DefaultValue</key>
<false/>
<key>Type</key>
<string>PSToggleSwitchSpecifier</string>
<key>Title</key>
<string>Underline Spell Check</string>
<key>Key</key>
<string>com.kindred.settings.underlineSpellCheck</string>
</dict>
</array>
</dict>
</plist>

Note: Make sure to change the ApplicationGroupContainerIdentifier (line 6) to match your App group identifier that you setup in step 4 of this setup guide

API Reference

The Kindred SDK gives several different settings that can be configured based on the commercial agreement with Kindred. These settings will define whether your users receive cashback and donate some of this to charity OR all of the savings are recognised as a donation, whether payout of any user savings is via Kindred or via yourselves, and settings that define location and currency for each user. Below are the key settings and the different options that should be selected based on your agreement.

Summary

Functions

configureKeyboard

setUserId
The UserId denoted below is used to uniquely identify users on your platform, and on the Kindred platform. It is the ID that will be used to link the user data from both sides. If your platform allows a single user account to be used on multiple devices, such as an iPad and iPhone or is device agnostic, you should ensure that the UserId is specific to the user and not the device.

Classes

KeyboardDisplayConfiguration
There are two key settings which will define the users’ keyboard experience;

1. Whether users will be able to withdraw any cashback through a Kindred hosted and co-branded wallet OR pay-out to users of their cashback will be done via your app/services or converting those savings into in app credit, points or in game currency.
2. Whether users will be earning cashback which they can choose to donate a percentage of, OR if all their cashback is converted into a donation.

showWithdrawal is used to define whether users will see a button on the keyboard prompting them to create a Kindred account to allow them to withdraw cashback via Kindred in a co-branded wallet area. If the button is shown, then users will be prompted to create a Kindred account. Thereafter, they will be able to view their earned cashback, available balance, and withdraw funds once the threshold has been met.

CashbackLabelType is used to set whether or not a user sees that they will be earning cashback and choosing to donate some of their savings, or donating all of their savings to charity through the UI.

The key UI experiences are:

Donations

Cashback

SettingsConfiguration

UserConfiguration
This defines the setup for each user as it relates to their location and currency.

Location will be used to filter the deals shown to each user, restricting the deals to the specified shipping country.

Currency will be used for all users and all cashback and/or donations received will be converted to this base currency and either paid directly to you or to the user depending on your agreement with Kindred.

CharityConfiguration
This defines which charity will receive the donations from each users’ earnings as well as the percentage split that will be made. These settings are independent of the display settings above.

CharityId is a valid Charity Id either received from the Kindred API or sent directly by the Kindred SDK Support Team based on your agreement. This is set per user.

CharityShare is the percentage of cashback that is donated to the selected charity from every received transaction for that user.

KindredInterface
This class contains the following static functions:

public static func isKeyboardExtensionEnabled() -> Bool
This function is used to determine whether the keyboard extension is enabled in the settings.

public static func hasFullAccess(appGroupName: String?) -> String
This function is used to determine whether full access setting is enabled for the keyboard extension. It takes the string representing the AppGroupName which is set in the info.plist as a parameter and returns a string from unknown/true/false

public static func isKeyboardActive(textField: UITextField?) -> String
This function is used to determine whether the custom keyboard is current active keyboard. It takes an UITextField object as a parameter and returns a string from unknown/true/false

public static func openSettings(app: UIApplication)
This function open the Settings app. It takes an UIApplication object as a parameter. Pass UIApplication.shared as the parameter.

KindredInterface.openSettings(app: UIApplication.shared)

Other
The file should be 40x40 and either a jpg or png

Troubleshooting

1. If you get the following error after pod install :

update the podfile to

source 'https://github.com/kindred-app/Specs.git'

target 'your_app_name' do
    pod 'KindredSDK', '2.0.10'
   
		target 'your_keyboard_target' do
        pod 'KindredSDK', '2.0.10'
    end
end

and run pod install

2. If you get the following error after pod install

or your pod version in Podfile.lock is not the same as podfile, run pod install --repo-update

3. Missing Info.plist
   If there is no Info.plist in your project navigator, you can make the changes to the Info tab of the target settings