Before You Begin
Integrating Kahuna with your app requires you to install the Kahuna SDK and then perform additional setup so that you can identify each of your users uniquely across all of their platforms, create cross-channel campaigns, and add attributes and events to create impactful marketing campaigns customized to the unique needs and goals of your business.
Prepare the following information before you start the integration process.
On which platform are you integrating Kahuna?
What type of credentials does your app use?
- Anonymous users only.
- Email, username, UserID.
- Other user credentials in addition to username, email and UserID, such as Facebook ID, Twitter ID.
See User Credentials below.
Which channels are you planning to use?
Kahuna provides a cross-channel approach of push notifications, email, in-app messaging, SMS messaging, and social networks.
- Push is supported on all platforms. See Push Notifications below.
- In-app messaging is supported on all platforms. See In-App Messaging below.
- Email is supported on all platforms. To send email campaigns through Kahuna, you need to work with Customer Success to set up and enable email sending options. See Email below.
- SMS is supported on iOS and Android. Contact Customer Success for information about setting up SMS.
Which custom attributes and events do you want to set up?
Kahuna enables you to create impactful marketing campaigns that are customized to the unique needs and goals of your business using attributes and events. Collaborate with your marketing analysts to identify custom attributes and events that are critical to your business. After integration, these attributes and events will be available in the Kahuna Campaign Creator and in Experiences. See Attributes and Events below.
Do you want your app to track events based on location?
Kahuna supports location monitoring for iOS and Android. See Location Monitoring below.
The following sections provide descriptions of the main integration points.
Kahuna uses credentials to differentiate itself from a system that only targets devices to one that has a person-centric view. To have a proper unified view of users across platforms and devices, all credentials you send to Kahuna must be unique and you must use the same credentials across all platforms (iOS, Android, Web).
Kahuna supports the following credential types:
- User ID—a globally-unique identifier (GUID), created by you, that helps you manage your users.
- Email—this credential is necessary if you want to reach a user with email.
- Username—a name you collect from the user in your mobile app and send to Kahuna. Your app must ensure that the user name is unique across all your users.
- Facebook ID—the user's Facebook ID. If you confirm that this is a valid ID assigned by Facebook, you can use it as a user credential. This credential is necessary if you want to reach a user with Facebook.
- Twitter ID—the user's Twitter ID. If you confirm that this is a valid ID assigned by Twitter, you can use it as a user credential.
- LinkedIn ID—the user's LinkedIn ID. If you confirm that this is a valid ID assigned by LinkedIn, you can use it as a user credential.
- Google Plus ID—the user's Google Plus ID. If you confirm that this is a valid ID assigned by Google Plus, you can use it as a user credential.
- Install Token—the user's install token.
- Mobile Number—the user's mobile phone number used for SMS messages. The mobile number must include the country code, area code, and number. Characters, such
+ - . ( )are not allowed. This credential is supported if you have integrated SDK for iOS 2.5.4 and above, or SDK for Android 2.4.6 (GCM) or 3.0.1 (Firebase) and above.
Kahuna creates a unified, person-centric profile of a user's activities, credentials, and devices regardless of the platform and device they use to interact with your product. When a user with credentials engages with your app on two separate devices, Kahuna combines user data from both devices by merging the credentials provided by the user on each device.
A user merge occurs either when an anonymous user logs in or when two users share a common credential on two devices.
Note: When Kahuna merges two user profiles, all user information, including top events, are combined in the user profile; however if any of the same attributes are used, Kahuna keeps the attributes of the newer user profile.
An anonymous user logs in
When a user is active within an app but has not yet logged in, Kahuna creates an anonymous profile for the device. If at anytime a user logs into the app on this device, Kahuna merges the profile for the device with the profile created for the logged in user. Kahuna keeps the attributes for the anonymous user.
Two users share a common credential on two devices
Any user credential you send to Kahuna is used to unify users across platforms and devices, so every credential must be globally unique.
Example: Kahuna merges two devices from the same user into a single user
Here is an example that shows a desirable merge; Kahuna aggregates user behavior across devices.
Jane likes to shop on ShopApp on her Android phone as well as her iPad. Kahuna has already tracked Jane on her Android phone and created a user profile for email@example.com. When Jane logs into ShopApp on her iPad, Kahuna merges her iPad user and behavior with her Android user under the same profile firstname.lastname@example.org.
Kahuna sees two devices from the same user.
Kahuna merges two devices from the same user into a single user.
Example: Kahuna merges two users when a credential is not unique
Here is an example that shows a user merge that occurs because a credential is not globally unique. This is an undesirable merge because Kahuna combines two different users into one user; Kahuna saves only attributes for the newer user in the profile.
Jane and John Smith both like to shop on ShopApp. When they log into the app, the app sends a username credential to Kahuna. The username is formed using the first initial and last name, and it is not globally unique. In this example, Jane and John have the same username, so Kahuna merges their user profiles.
Kahuna sees several users.
Kahuna merges JSmith based on common credentials.
The Kahuna system facilitates push notifications to mobile devices.
Kahuna supports deep links in push notifications for iOS and Android. See Does Kahuna support deep linking?
iOS Push Notifications
In iOS, push notifications use the Apple Push Notification Service (APNS). Kahuna acts as an intermediary on your behalf, managing APNS tokens for your users and sending your notifications to Apple for distribution to your users.
iOS Push Notification Environments
Kahuna uses a single secret key schema to avoid switching keys before deploying a production build.
Kahuna detects the value set for the aps-environment and device model to route traffic between the production and sandbox namespaces. If the device model is a simulator, traffic is sent to the sandbox namespace. If the aps-environment is not production, traffic is sent to the sandbox namespace. All other traffic goes to production.
Note: Push does not work on the iOS Simulator. You have to test push messages on an actual iOS device.
The Kahuna SDK for iOS provides a feature called Deep Integration, which allows Kahuna to perform method swizzling on some functions in your application delegate. Swizzling allows the SDK to handle the API calls needed for push messaging. Deep integration reduces the amount of code you need to integrate push notifications into your app. If you prefer not to use swizzling, you can add push messaging to your app manually.
iOS Push Tokens
A push token gives Kahuna authorization to send push notifications through APNS to a specific device. Push tokens are different from APNS certificates. An APNS certificate authenticates and authorizes Kahuna with the service. A push token is also different from a device ID, which is a user credential that Kahuna creates and assigns to a device that has your app.
Your app has to request a push token from APNS for the device and provide it to the Kahuna SDK. You usually do this when the user first installs your app and logs in. After you have established the push token, the Kahuna SDK refreshes the push token automatically.
iOS Push Notification Behavior
The IOS platform standardizes how push notifications are displayed, which limits your ability to customize them. Be sure to test your push notifications with all of the display options that iOS provides.
Push notifications are not displayed if your app is already in the foreground when you receive the notification. The Kahuna SDK invokes the Kahuna Push Delegate if you have it registered, but the message does not appear in the Notification Center.
Android Push Notifications
The Android environment sends push notifications using Google Firebase Cloud Messaging for Android. Kahuna acts on your behalf to manage authentication with Google servers and to send push notifications to Android devices through Google Firebase servers.
The first and most important integration step is to obtain a Firebase Cloud Messaging Server key from Google and add it to your Kahuna account. To send a push notification to an Android device, Kahuna needs to authenticate itself with Firebase; the Server Key contains that authentication.
Make sure you update your account with the correct Firebase Cloud Messaging Server key; otherwise, your push campaigns will start to fail.
Production and Development Builds
Make sure that the correct Firebase
google-services.json file is stored in the root directory of your app. Also, make sure you add the app to your Firebase Project.
Android push tokens allow Kahuna to send a push notification to a specific device, but they are not the same as the device ID that Kahuna assigns. Instead, Firebase generates push tokens independently of the device ID. A user must have at least one active push token to receive push notifications. The SDK handles refreshing push tokens on the device.
Cordova/PhoneGap Push Notifications
The Kahuna Cordova SDK implementation uses both the Android and iOS native SDKs.
JavaScipt - Web Push Notifications
The Kahuna SDK supports in-app messaging, which is an additional communications channel that helps you display messages directly inside your mobile app or web interface. Together with an in-app messaging campaign you create using Kahuna, the in-app messaging feature sends a message through the SDK to your app or web interface. You can then display the message in your own UI.
Because in-app messaging is a separate channel, Kahuna delivers in-app messages to your app or web interface regardless of push notification settings. This allows you to send in-app messages to users who do not have push enabled.
SDK 2.4.0 and above supports Marketer-Driven In-App Messaging, which enables you to develop messages with unique content and multiple template styles provided by Kahuna. However, if your app or web interface already has a style that you want to keep when you show UI elements, you can implement Custom In-App Messaging.
Kahuna supports deep links in in-app messages for iOS and Android. See Does Kahuna support deep linking?
Kahuna needs to obtain certain information from you to be able to set up and enable your email campaigns. You need to share the following information with Customer Success:
- A list of valid domains from which your email will be sent.
An estimate of how many email messages you intend to send your customers on a daily basis during the first four to six weeks. This information enables Customer Success to develop a warmup plan.
When a mailbox provider sees unexpectedly large volumes of email coming from a new IP address or domain, they might be suspicious of your intent and deliver your email to the junk folder or bounce your emails entirely. This can damage your sender reputation and limit the effectiveness of your email campaigns for many months. To establish a positive reputation as a legitimate email sender, you need to increase the volume of email you send gradually. Kahuna provides a warmup period where the volume of email sent from the domain is gradually increased according to a predetermined schedule.
- A list of Kahuna users that have permission to send email campaigns. The Reply-to list for outgoing emails must match this list.
The default Bcc recipient for any outgoing email messages.
The default URL you want to provide to your users in campaigns to unsubscribe from email.
- The URL you want to use for your application to receive email bounce, unsubscribe, spam, and reject information from Kahuna.
In addition to the above information, your DNS administrator needs to add two TXT records to the each domain being used for Kahuna in your DNS provider settings. Your Customer Success Manager will provide these TXT records to you.
Kahuna enables you to create impactful marketing campaigns that are customized to the unique needs and goals of your business using attributes, simple events, and intelligent events.
- Attributes identify users and personalize content. For example, first name, gender, last login date, or last purchase. You can update attributes any time.
- Events are user actions, such as made a purchase, shared an item, marked an item as a favorite. These simple events have no additional information.
- Intelligent Events are events with additional properties that help to further define the event, such as made a purchase of a DVD called Avengers (where made purchase is the event, DVD is a property key, and Avengers is the property value). Intelligent events are used to help show historical usage of a user. The properties are attached directly to their events.
Kahuna provides some core attributes and events, however, you need to collaborate with your marketing analysts to identify custom attributes and events that are critical to your business. After you have identified the attributes and events you want to use, you need to add code to your app that sends information to Kahuna when a user takes action so that you can target campaigns appropriately.
Note: Not all core attributes and events are available for filtering in campaigns; for example,
|Last Email Sent|
|Last Push Sent|
|Last Reached Out To|
|Last SMS Sent|
|iOS Push Enabled|
|Android Push Enabled|
|Web Push Enabled|
Custom Attribute Examples
Custom Event Examples
Intelligent Event Examples
|Example Intelligent Event||Example Property Key||Example Property Value|
Location Monitoring lets you use Kahuna to track events based on a location.
After you complete the integration for location monitoring for your platform, work with your Customer Success Manager to enable Location Monitoring and set up the regions you want to monitor. See also Regions to Monitor