iOS

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 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 UA 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 sandbox server environment
   • applinks:promotion.qpyou.cn: Universal Link domain for the 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 URLs that, when clicked by users, direct them to specific locations within the game app (after installing the game app) or expose specific web views to encourage user engagement.

The destination address where users navigate through direct links is set in Hive Console > Direct Link Management, and various destinations such as marketplaces, specific locations within the game app (deep links), and specific web views can be flexibly configured according to the user's OS environment.

The operational sequence when direct links are applied in conjunction with the game app is as follows:

1. Share direct links as various destination links (market links, deep links, web URLs)
2. When a user clicks a direct link, it operates as follows according to the destination set in Hive Console > Direct Link Management: - Market navigation: Regardless of the user's game app installation status, navigate to the market link set in Hive Console > Direct Link Management - In-app navigation (deep link) - If the game app is installed in the user's environment: Navigate to the designated location within the game app (scheme deep link) - If the game app is not installed in the user's environment: Navigate to the game app installation location in the market supported by each OS environment or the uninstalled user redirect URL set when creating the deep link - Web URL: Regardless of the user's game app installation status, navigate to a specific web view outside the game
3. When the user proceeds in the order of 'game app launch > login > user engagement (UE) SetReady operation', the event included in the link information is executed in the game app (performing related functions or UI exposure, performing custom functions defined in UE, etc.)

Xcode project setup¶

To apply direct link functionality in the iOS target Hive SDK, configure your Xcode project in the following order:

1. Select the main TARGETS in your Xcode project.
2. In the Associated Domains section of the Signing & Capabilities tab, configure the domains as follows:

   * <i>applinks:sandbox-direct-link.withhive.com</i>: Universal link domain for direct link functionality operating in sandbox server environment
   * <i>applinks:direct-link.withhive.com</i>: Universal link domain for direct link functionality operating in production server environment