iOS

Hive SDK for iOS provides a promotion feature. This document describes how to configure an iOS app to use the promotion feature.

Using Universal Links¶

Universal Links allow users to install and launch the app through invitation pages and enable inviter rewards. The Hive SDK for iOS supports both URI Scheme-based and Universal Link-based deferred deep links.

Common Setup¶

To use Universal Links, follow these common setup steps.

Server Setup¶

1. Prepare the following values for your environment and save them in an apple-app-site-association file:
   • TEAM ID: Your TEAM ID from the Apple Developer Console
   • Bundle Identifier: The bundle ID of the app using Universal Links
   • URL Path: The HTTP URL path to support Universal Links

2. Upload the apple-app-site-association file to the root of your web server or to the .well-known subdirectory. The file must be in JSON format and should not have an extension.

   Example apple-app-site-association file:

   {
       "applinks": {
           "apps": [],
           "details": [
               {
                   "appID": "--TEAM ID.--Bundle Identifier",
                   "paths": ["--URL Path"]
               }
           ]
       }
   }
   

   
   Example from Apple:

   {
       "applinks": {
           "apps": [],
           "details": [
               {
                   "appID": "9JA89QQLNQ.com.apple.wwdc",
                   "paths": ["/wwdc/news/", "/videos/wwdc/2015/*"]
               }, {
                   "appID": "ABCD1234.com.apple.wwdc",
                   "paths": ["*"]
               }
           ]
       }
   }
   

iOS App Setup¶

Set up your iOS app in Xcode as follows:

1. In the Xcode project navigator, select your project.
2. Select your app from the TARGETS list.
3. Click the Signing & Capabilities tab.
4. Click the + Capability button at the top left of the Signing & Capabilities tab.
5. Add Associated Domains from the list.
   • Example domain: applinks:hive-ota.withhive.com
     
6. Enable Associated Domains in the app's Capabilities in the Apple Developer Console.

Using Deferred Deep Links¶

Deferred deep links allow users to launch the app via Universal Link invitation links and enable inviter rewards. UIPasteboard permission is required for deferred deep links. When a user installs and launches the app for the first time using an invitation link, a toast popup may appear on iOS versions below 16.1, and a system permission request popup may appear on iOS 16.1 and above. To disable the system permission popup, refer to the Promotion Operation Guide and set deferred deep links to "disabled".

Xcode Project Setup¶

To use deferred deep links, configure your Xcode project as follows:

1. Select the main TARGETS in your Xcode project.

2. In the Signing & Capabilities tab, add the following domains under Associated Domains:

   • applinks:sandbox-promotion.qpyou.cn: Universal Link domain for the Hive sandbox server environment
   • applinks:promotion.qpyou.cn: Universal Link domain for the Hive production server environment

hive_config.xml Setup¶

Add the following code to the hive_config.xml file in your SDK:

<universalLink>Universal link address (Domain/Path)</universalLink>

Using Direct Links¶

Direct links are provided as a single URL and can be used for both user acquisition (UA) invitation links and user engagement (UE, deep link) features.

The flow for using Hive User Acquisition (UA) and Hive User Engagement (UE) with direct links is as follows:

1. User A shares a direct link invitation.
2. User B accesses the app via the shared link; the server analyzes the link to confirm that B accepted A's invitation and obtains reward information.
3. Immediately after accessing the app, UE actions defined in the link are performed (Hive features, UI display, or custom actions defined by the game app).
4. If the app is not installed on B's device, the link prompts installation. If already installed, the app launches and sends A and B's information to the promotion server.

To use direct links, refer to the Promotion Setup Guide and configure direct links in the console. Xcode project setup is also required.

Xcode Project Setup¶

To use direct links, configure your Xcode project as follows:

1. Select the main TARGETS in your Xcode project.

2. In the Signing & Capabilities tab, add the following domains under Associated Domains:

   • applinks:sandbox-direct-link.withhive.com: Universal Link domain for the Hive sandbox server environment (direct link feature)
   • applinks:direct-link.withhive.com: Universal Link domain for the Hive production server environment (direct link feature)