iOS完整参考

迦太基兼容迦太基兼容 麻省理工学院许可麻省理工学院许可

可用于 CocoaPods

分支可通过 CocoaPods 。要安装它,只需将以下行添加到您的Podfile中:

pod 'Branch'

然后,从命令行cd到您的项目目录,然后执行以下操作:

pod install
pod update

安装 Branch pod 并将其更新到最新版本的 SDK。

确保执行pod update 。否则,CocoaPods 可能不会使用最新版本的 SDK!

迦太基

要使用 Carthage 将 Branch 集成到您的项目中,请将以下内容添加到Cartfile

github "BranchMetrics/ios-branch-deep-linking"

下载原始文件

您也可以通过下载以下原始文件进行安装。

将 Raw Files Branch SDK 添加到您的项目

如果您不想通过 Cocoapods 或 Carthage 而直接添加 Branch SDK,请将Branch 作为动态框架依赖项添加到项目中。

我将 Branch 添加到 “BareBones” 项目作为示例:

  1. 将 Branch SDK 文件下载或 git clone 到您的计算机。

  2. 如果您已经将 Branch 添加到您的项目中,请将其删除。

  3. In the Xcode project navigator view, select your project, right click, and select 'Add files to "<your project name>"...'

Add Files...Add Files...

  1. “Add” 文件选择器将打开。前往 “ios-branch-deep-linking>carthage-files 目录,然后选择 BranchSDK.xcodeproj 项目。

Add BranchSDK.xcodeprojAdd BranchSDK.xcodeproj

Xcode 会将 BranchSDK.xcodeproj 添加到您的项目中。

  1. 在您的项目中,显示 "BranchSDK.xcodeproj>Product" 层次结构。然后将 Branch.framework 产品拖动到构建产品的 “Embedded Binaries” 部分。

Embed BinaryEmbed Binary

  1. 完成!您可以点击项目的“构建阶段”,以确保将 Branch 添加为目标依赖项并复制为嵌入式框架。

Check Build PhaseCheck Build Phase

注册您的应用

您可以在 https://dashboard.branch.io 注册自己的应用程序ID。

将您的 Branch key 添加到您的项目中

注册应用程序后,可以在仪表板的“ 设置页面上检索分支键。现在,您需要将其添加到YourProject-Info.plist(Swift的Info.plist)。

  1. 在 plist 文件中,将鼠标悬停在“信息属性列表(Information Property List)”上,这是 Key 列下的根项目。
  2. 大约半秒钟后,您将看到一个“ +”号出现。点击它。
    3在新添加的行中,为其键填写“ branch_key”,将类型保留为String,然后在值列中输入在上述步骤中获得的应用程序的分支键。
  3. 保存 plist 文件。

Branch Key DemoBranch Key Demo

如果要同时为动态和测试应用添加 key,则需要将类型列更改为 Dictionary,并在其中添加两个条目:

  1. 对于动态应用程序,将 "live"(不带双引号)用于 key,将 String 用于类型,将 live branch key 用于值。
  2. 对于测试应用程序,将 "test"(不带双引号)用于 key,将 String 用于类型,将 test branch key 用于值。

Branch Multi Key DemoBranch Multi Key Demo

注意:如果您使用了 Fabric 将 Branch 作为工具包安装,那么 Branch key 将作为 Fabric > Kits 数组下的元素位于 Info.plist 中,如下所示:

Branch Fabric KeysBranch Fabric Keys

注册 URI Scheme

通过在 YourProject-Info.plist 文件中添加 URI scheme,注册您的应用程序以响应直接深度链接(在移动浏览器中为 yourapp://)。确保将 yourapp 更改为代表应用程序名称的唯一 string。

  1. 在 Xcode 中,点击左侧的 YourProject-Info.plist。
  2. 查找 URL 类型,然后点击右箭头。 (如果不存在,请右键点击任意位置,然后选择添加行(Add Row)。向下滚动并选择 URL 类型)。
  3. 添加 “yourapp” 作为 URL Scheme 的一项,其中 yourapp 是应用程序的唯一 string。

警告:您的应用 URI scheme 必须是列表中定义的第一个方案(项目0)。

如果您定义了多个方案,例如 Facebook 登录 URI,请使您的应用程序的 URI scheme 成为列表中的第一个方案,以便 Branch SDK 知道特定于您的应用程序的 URI。

URL Scheme DemoURL Scheme Demo

或者,您可以在项目的信息(Info)页面中添加 URI scheme。

  1. 在 Xcode 中,在 Navigator(左侧)点击您的项目。
  2. 选择"信息(Info)"标签。
  3. 展开底部的 "URL Types" 部分。
  4. 点击"+"符号以添加新的 URI scheme,如下所示:

URL Scheme DemoURL Scheme Demo

支持 Universal Linking(iOS 9及更高版本)

在 iOS 9中,Apple 添加了一种功能,可允许 http 链接直接打开您的应用程序,而不是通过 URI Scheme。这设置起来会很麻烦,因为它涉及服务器上的复杂过程。好消息是,Branch 仅需两个步骤即可为您完成这项工作!

  1. 在 Xcode 中,在 Navigator(左侧)点击您的项目。
  2. 选择"功能(Capabilities)"选项卡。
  3. 展开"关联域(Associated Domains)"选项卡。
  4. 启用设置(切换开关)。
  5. applinks:xxxx.app.linkapplinks:xxxx-alternate.app.link添加到列表中。确保xxxx与您的应用程序的4个字符子域匹配(您可以在 仪表板上的找到它)。如果您使用自定义子域,请使用它代替x(例如imgur.app.linkimgur-alternate.app.link )。
  6. 添加您拥有的任何额外的自定义域(例如applinks:vng.io

Xcode Enable ULXcode Enable UL

  1. 在操作后台 (Dashboard),前往应用程序的链接设置页面。
  2. 选中"启用 Universal Link
  3. 确保您的 Apple Team ID 和 App Bundle ID 是正确的(我们会尝试自动为您收集它们)。
  4. 确保保存这些设置更新。

Dashboard Enable ULDashboard Enable UL

自定义域名配置(如果您不使用 Branch 提供的 xxxx.app.link 域,则为必填项)

Branch 为您的应用程序提供了一个 xxxx.app.link 域,但是您可以使用自己的自定义域来创建 app link。如果您确实要将自己的自定义域用于 universal app link,则需要将其添加到 Info.plist。

使用自定义域将branch_universal_link_domains key 添加为 string 值:

Custom Domain Info.plistCustom Domain Info.plist

URI Scheme 注意事项

Branch SDK 将从您的列表中提取第一个 URI Scheme,该方案不是fbdbpin 。该值将被使用一次来在 Branch 操作后台 (Dashboard)的“链接设置(Link Settings)”下设置iOS URI Scheme。

有关配置SDK的其他帮助(包括分步说明),请参阅《 iOS快速入门指南

获取 Singleton Branch 实例

所有 Branch 方法都需要 Branch 主要对象的实例。下面将说明您如何将其获取。它是静态存储的,可以从任何类访问。

方法

Branch *branch = [Branch getInstance];
let branch: Branch = Branch.getInstance()

测试

测试您的Branch集成

通过在AppDelegate中调用validateSDKIntegration 来测试Branch集成。检查您的Xcode日志,以确保所有SDK集成测试都通过。确保在生产版本中注释掉或删除validateSDKIntegration

Branch.getInstance().validateSDKIntegration()
[[Branch getInstance] validateSDKIntegration];

测试 Branch Link 的深度链接路由

?bnc_validate=true 附加到您的任何应用程序的Branch链接上,然后在移动设备(不是Simulator!)上点击它以开始测试。例如,要验证以下链接: "https://<yourapp\>.app.link/NdJ6nFzRbK" 点击: "https://<yourapp\>.app.link/NdJ6nFzRbK?bnc_validate=true"

//TODO: Remove for launch
Branch.setUseTestBranchKey(true)
#warning Remove for launch
[Branch setUseTestBranchKey:YES];

参量

分支键 (NSString *) 可选
如果不将Branch键存储在plist文件中,则可以选择将此键作为参数传递。

初始化 Branch 会话和深度链接路由功能

要进行深度链接,Branch 必须初始化会话以检查用户是否源自链接。每次打开应用时,此调用都会初始化一个新的会话 。在应用程序打开的时间中,有100%的时间,它将调用深度链接处理块来通知您用户是否来自链接。处理块来通知您用户是否来自链接。如果您的应用程序打开时在参数中带有 key,您则需要根据传入的数据来路由用户。否则,请将其发送到通用屏幕。

方法

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  let branch: Branch = Branch.getInstance()
  branch?.initSession(launchOptions: launchOptions, deepLinkHandler: { params, error in
    if error == nil {
        // params are the deep linked params associated with the link that the user clicked -> was re-directed to this app
        print("params: %@", params.description)
    }
   })
  return true
}

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    // Pass the url to the handle deep link call
    let branchHandled = Branch.getInstance().application(
        application,
        open: url,
        options: options
    )
    if (!branchHandled) {
        // If not handled by Branch, do other deep link routing for the
        // Facebook SDK, Pinterest SDK, etc
    }

    return true
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    let handledByBranch = Branch.getInstance().continue(userActivity)

    return handledByBranch
}

func application(_ application: UIApplication, didReceiveRemoteNotification launchOptions: [AnyHashable: Any]) -> Void {
    Branch.getInstance().handlePushNotification(launchOptions)
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Branch *branch = [Branch getInstance];
    [branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
        // route the user based on what's in params
    }];
    return YES;
}

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    BOOL branchHandled =
        [[Branch getInstance]
            application:application
                openURL:url
                options:options];
    if (!branchHandled) {
        // do other deep link routing for the Facebook SDK, Pinterest SDK, etc
    }
    return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *restorableObjects))restorationHandler {
    BOOL handledByBranch = [[Branch getInstance] continueUserActivity:userActivity];

    return handledByBranch;
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [[Branch getInstance] handlePushNotification:userInfo];
}

注意:如果您的应用程序委托声明了该方法:

- (BOOL) application:willFinishLaunchingWithOptions:

在 Swift 中:

optional func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool

它必须返回YES 才能使 Branch 工作。

参量

initSession

launchOptions (NSDictionary *) 必需
这些启动选项通过didFinishLaunchingWithOptions传递给Branch,并将通知用户是否来自URI调用。如果应用是通过myapp://之类的URI打开的,则需要遵循特殊的初始化例程。

deepLinkHandler ^(NSDictionary 参数,NSError错误) 可选
这是在网络调用以确定用户来自哪里之后,Branch将执行的回调块。自分支机构注册生命周期通知以来,它被称为应用程序打开时间的100%。

  • NSDictionary *参数
    这些参数将包含与应用程序会话开始之前单击的与Branch链接关联的所有数据。总是有一些键:
    -'+ is_first_session'表示这是第一个会话(安装)还是任何其他会话(打开)
    -'+ clicked_branch_link'表示用户是否单击了触发该会话的分支链接
  • NSError *错误
    除非存在连接或其他错误,否则此错误将为nil。检查!error以确认它是有效的链接。
    -BNCServerProblemError连接到分支服务时出现问题
    -BNCBadRequestError请求的格式不正确

Branch 每次都返回显式参数。这里有一个列表,以及与其相对应的描述。

  • ~ 表示分析
  • + 表示Branch添加的信息
  • (给好奇者, $ 表示用于控制 Branch 服务行为的保留关键字)
参数意义
~channel在创建链接时指定共享链接的通道
~feature在链接创建时指定的功能,例如inviteshare
〜标签在链接创建时指定的任何标签
~campaign与链接关联的广告系列,在链接创建时指定
〜阶段在链接创建时指定的阶段
~creation_source其中链路被创建( ' API ' , '仪表板' , ' SDK ' , '的iOS SDK ' , '的Android SDK ' ,或'的Web SDK ' )
+match_guaranteed关于匹配是否以100%的准确性进行的判断是对还是错
+referrer点击链接的引荐来源网址(如果点击了链接)
+phone_number用户的电话号码(如果用户通过短信将应用发送给自己)
+is_first_session表示这是第一个会话(安装)还是任何其他会话(打开)
+clicked_branch_link表示用户是否点击了触发该会话的Branch链接
+click_timestamp点击发生的时间时间戳记

isReferrable (BOOL) optional:
This boolean lets you control whether or not the user is eligible to be 'referred'. This is applicable for credits and influencer tracking. If isReferrable is set to NO | false, and the user clicks a link before entering the app, deep link parameters will appear, but that user will not be considered referred. If isReferrable is set to YES | true, and the user clicks a link, deep link params will appear and the user will be considered referred. Remove this argument to access the default, which only allows the user to be referred on a fresh install, but not on opens.

automaticallyDisplayDeepLinkController (BOOL) optional:
This boolean lets you control whether or not the Branch should attempt to launch Deep Linked controllers (based on those registered with [branch registerDeepLinkController:forKey:]). The default is NO | false.

handleDeepLink

url (NSString *) 必填
此参数传递给我们URI字符串,以便我们可以解析额外的参数。例如,“ myapp:// open?link_click_id = 12345”。

continueUserActivity

userActivity(NSUserActivity *) 要求
此参数将用户活动传递给我们,以便我们可以解析原始URL。

退货

initSession

handleDeepLink

BOOL handleDeepLink 将返回一个布尔值,指示 Branch 是否已处理 URI。如果 URI 调用是'myapp://open?link_click_id=12345' ,则 handleDeepLink 将返回 YES,因为存在 Branch 点击对象。如果只有 'myapp://' ,handleDeepLink 将返回 NO。

continueUserActivity

BOOL continueUserActivity 将返回一个布尔值,指示 Branch 是否已处理 Universal Link。如果 Universal Link 由 Branch 提供支持,则由于存在 Branch 点击对象,continueUserActivity 将返回 YES。

如果您使用自己的自定义通用链接域,请确保按照此处所述将其Info.plist添加到branch_universal_link_domains键下,否则,实际上打开通用链接时,此方法可能会错误地返回NO

注册深度链接控制器

注册一个 Branch 控制器,以显示 Branch open/install 字典中是否存在特定 key。这是处理自动深度链接的机制,应在initSession之前调用。

方法

Branch.getInstance().registerDeepLinkController(myController forKey:"my-key" withPresentation: .optionShow)
[[Branch getInstance] registerDeepLinkController:myController forKey:@"my-key" withPresentation:BNCViewControllerOptionShow];

参量

控制器 (UIViewController *) 必填
当字典中存在键时显示的控制器。

密钥 (NSString *) 必需
在打开/安装词典中检查了该键。

Option (BNCViewControllerPresentationOption) required
| Option | Meaning
| --- | ---
| BNCViewControllerOptionShow | This option pushes view controller onto the navigation stack in a similar way as the showViewController
| BNCViewControllerOptionPush | This option pushes view controller onto the navigation stack in a similar way as the pushViewController
| BNCViewControllerOptionPresent | This option presents view controller onto the root view controller of window in a similar way as the presentViewController

退货

检索会话(安装或打开)参数

这些会话参数在此命令之后随时可用。如果没有可用参数,则 Branch 将返回一个空字典。这会刷新每一次的新会话(应用安装和应用打开)。

警告:如果 Branch SDK 正在通过网络调用检索最新的会话参数,则此方法将返回前一个会话的参数。最佳实践是在 Branch 初始化时设置回调深度链接处理程序。当处理了 Branch 深度链接并且最新的会话参数可用时,该处理程序将被调用。

否则,请使用getLatestReferringParamsSynchronous 方法。此方法始终返回最新的会话参数。它的缺点是可能阻塞调用线程,直到当前结果可用为止。

方法

Objective-C
// This is an example of `getLatestReferringParams`.
// Warning: It may return the previous results.
NSDictionary *sessionParams = [[Branch getInstance] getLatestReferringParams];

// This is an example of `getLatestReferringParamsSynchronous`.
// Warning: It may block the current thread until the latest results are available.
NSDictionary *sessionParams = [[Branch getInstance] getLatestReferringParamsSynchronous];
Swift
// This is an example of `getLatestReferringParams`.
// Warning: It may return the previous results.
let sessionParams = Branch.getInstance().getLatestReferringParams()

// This is an example of `getLatestReferringParamsSynchronous`.
// Warning: It may block the current thread until the latest results are available.
let sessionParams = Branch.getInstance().getLatestReferringParamsSynchronous()

参量

退货

NSDictionary*

当 initSession 返回在深度链接回调中设置的参数时,我们会在会话期间将其存储在 NSUserDefaults 中,以备日后检索时使用。请注意,一旦应用被最小化并且会话结束后,它将被清除。

检索安装(仅安装)参数

如果要访问原始会话参数(仅为第一个 install 事件传递的参数),则可以使用此行。如果您只想奖励通过推荐链接来新安装应用程序的用户,这会很有用。请注意,当调用setIdentity:并进行身份合并时,可以更新这些参数。

方法

Objective-C
NSDictionary *installParams = [[Branch getInstance] getFirstReferringParams]; // previously getInstallReferringParams
Swift
let installParams = Branch.getInstance().getFirstReferringParams() // previously getInstallReferringParams

参量

持久身份

通常,您可能拥有自己的用户 ID,或者希望引用和事件数据在各个平台之间持久存在或进行卸载/重新安装。如果您知道您的用户可以从不同的设备访问您的服务,那么这将很有帮助。这里我们介绍'身份'的概念。

方法

要识别用户,只需调用:

Objective-C
// previously identifyUser:
[[Branch getInstance] setIdentity:your user id];    // your user id should not exceed 127 characters
Swift
// previously identifyUser:
Branch.getInstance().setIdentity(your user id)  // your user id should not exceed 127 characters

参量

身份 (NSString *)为必填项
这是您要在Branch系统中标记用户的别名。请注意,我们仅支持每个用户使用一个别名。

注销

如果您在应用程序中提供注销功能,请确保在注销完成后清除用户。这将确保清除所有存储的参数,并将所有事件归因于正确的身份。

警告 :此调用将清除设备上的促销积分和归因。

方法

Objective-C
[[Branch getInstance] logout];  // previously clearUser
Swift
Branch.getInstance().logout()   // previously clearUser

参量

追踪用户操作和事件

使用BranchEvent 接口可以追踪特殊的用户操作或特定于应用程序的事件,而不仅仅是应用程序的安装,打开和共享。您可以追踪事件,例如用户何时将商品添加到在线购物车或搜索关键字等。

BranchEvent 接口提供了用于添加 BranchUniversalObject 表示内容的接口,以便将应用程序内容与事件相关联。

有关应用程序 BranchEvents 的分析可在 Branch 操作后台 (Dashboard)找到,并且 BranchEvents 还提供与许多第三方分析提供商的紧密集成。

BranchEvent 类很容易使用。例如:

Objective-C
[[BranchEvent standardEvent:BranchStandardEventAddToCart] logEvent];
Swift
BranchEvent.standardEvent(.addToCart).logEvent()

为了获得最佳结果,请使用BranchEvent.h定义的 Branch 标准事件名称。但是您也可以使用自己的自定义事件名称:

Objective-C
[[BranchEvent customEventWithName:@"User_Scanned_Item"] logEvent];
Swift
BranchEvent.customEventWithName("User_Scanned_Item").logEvent()

额外事件特定数据也可以通过事件进行追踪:

Objective-C
BranchEvent *event    = [BranchEvent standardEvent:BranchStandardEventPurchase];
event.transactionID   = @"tx-12344555";
event.currency        = BNCCurrencyUSD;
event.revenue         = [NSDecimalNumber decimalNumberWithString:@"12.70"];
event.shipping        = [NSDecimalNumber decimalNumberWithString:@"10.20"];
event.tax             = [NSDecimalNumber decimalNumberWithString:@"2.50"];
event.coupon          = @"coupon_code";
event.affiliation     = @"store_affiliation";
event.eventDescription= @"Shopper made a purchase.";
event.searchQuery     = @"Fashion Scarf";
event.contentItems    = @[ branchUniversalObject ];
event.customData      = (NSMutableDictionary*) @{
    @"Item_Color": @"Red",
    @"Item_Size":  @"Large"
};
[event logEvent];
Swift
let event = BranchEvent.standardEvent(.purchase)
event.transactionID    = "tx-12344555"
event.currency         = .USD
event.revenue          = 12.70
event.shipping         = 10.20
event.tax              = 2.50
event.coupon           = "coupon_code"
event.affiliation      = "store_affiliation"
event.eventDescription = "Shopper made a purchase."
event.searchQuery      = "Fashion Scarf"
event.contentItems     = [ branchUniversalObject ]
event.customData       = [
    "Item_Color": "Red",
    "Item_Size":  "Large"
]
event.logEvent()

注册自定义事件(不建议使用)

对于使用推荐的客户

如果您使用的是 Branch 的推荐功能,请通过userCompletedAction方法使用下面提供的旧版文档。不要升级到新的BranchEvent方法来追踪上述用户操作。

方法

Objective-C(已弃用)
[[Branch getInstance] userCompletedAction:@"your_custom_event"]; // your custom event name should not exceed 63 characters
迅捷(已弃用)
Branch.getInstance().userCompletedAction("your_custom_event") // your custom event name should not exceed 63 characters

或者,如果您想与事件一起存储某些状态:

Objective-C(已弃用)
[[Branch getInstance] userCompletedAction:@"your_custom_event" withState:(NSDictionary *)appState]; // same 63 characters max limit
迅捷(已弃用)
Branch.getInstance().userCompletedAction("your_custom_action", withState: [String: String]()) // same 63 characters max limit; replace [String: String]() with params dictionary

您可能想要追踪的一些示例事件:

@"complete_purchase"
@"wrote_message"
@"finished_level_ten"

参量

事件 (NSString *) 必填
这是您要发送给Branch的事件字符串。您可以在分析中查看导致事件发生的链接的归属。

状态 (NSDictionary *) 可选的
如果您想随事件一起传递其他元数据,则应使用此字典。例如,这就是使用BNCPurchaseAmount常量作为键将收入传递到Branch的方法。

Apple Search Ads

Branch可通过从以下位置获取搜索广告归因来帮助跟踪您的Apple搜索广告活动
苹果在应用程序安装。然后,您可以使用在Apple搜索广告信息中心中设置的参数,
参数,例如广告系列名称,并在安装后在您的应用中采取特殊措施,或者
在分支仪表板以及其他分支中跟踪活动的有效性
统计信息,例如总安装,引荐和应用链接统计信息。

方法

- (void) delayInitToCheckForSearchAds

调用此方法以启用在分支初始化之前检查Apple Search Ads。这个方法
必须在初始化分支会话之前调用它。

有关更多信息,请参阅Apple Search Ads文档

Objective-C
[[Branch getInstance] delayInitToCheckForSearchAds];
Swift
Branch.getInstance().delayInitToCheckForSearchAds

启用或禁用用户追踪

为了符合追踪要求,您可以在 SDK 级别禁用追踪。您只需调用:

[Branch setTrackingDisabled:YES];
Branch.setTrackingDisabled(true)

这将防止发送任何 Branch 网络请求(深度链接除外)。如果有人点击 Branch Link,但又不想被追踪,我们会将深度链接数据返回给应用程序,但不会捕获任何追踪信息。

在 “do-not-track” 模式下,您仍然可以创建和共享链接。链接没有可识别的信息,且将是长格式链接。如果用户表示不想被追踪,则事件追踪不会将数据传回服务器。您可以随时通过调用上述函数来更改此行为。 trackingDisabled 状态已被保存并在应用程序运行期间持续存在。

Branch Universal Object(用于深度链接,内容分析和索引编制)

随着 iOS 中更多方法的演变,我们发现越来越难以管理所有这些方法。我们尽可能多地将其抽象化到一个 Branch Universal Object 的概念。它与您要共享的事物(内容或用户)相关联。您可以设置与该对象关联的所有元数据,然后调用操作方法以在 Spotlight 中获取链接或索引。

Branch Universal Object 最佳实践

这里有一组最佳实践,可确保您的分析正确无误,并且您的内容有效地在 Spotlight 上排名。

  1. 跨应用实例将canonicalIdentifier 设置为唯一的重复数据消除值
  2. 确保titlecontentDescriptionimageUrl 适当地表示对象
  3. 初始化 Branch Universal Object,并在页面加载时BNCRegisterViewEvent调用userCompletedAction
  4. 当用户执行需要链接的操作时,请在生命周期的稍后阶段调用showShareSheetcreateShortLink
  5. 当采取相应的用户操作时,调用其他对象事件(购买,共享完成等)
  6. contentIndexMode设置为ContentIndexModePublicContentIndexModePrivate 。如果 BranchUniversalObject 设置为ContentIndexModePublic ,则内容将使用NSUserActivity进行索引,否则内容将使用 Spotlight 上的CSSearchableIndex进行索引。

注意:使用CSSearchableItem索引的内容可以从 Spotlight 中删除,但是如果使用NSUserActivity索引的内容则不能删除。

需要避免的做法:

  1. 不要在所有对象上设置相同的titlecontentDescriptionimageUrl
  2. 请不要等到用户共享再初始化对象并注册视图。
  3. 请不要等到您需要链接再初始化对象。
  4. 不要一次创建多个对象,并在for循环中注册视图。

Branch Universal Object

方法和属性

Objective-C
#import "BranchUniversalObject.h"
BranchUniversalObject *branchUniversalObject = [[BranchUniversalObject alloc] initWithCanonicalIdentifier:@"item/12345"];
branchUniversalObject.title = @"My Content Title";
branchUniversalObject.contentDescription = @"My Content Description";
branchUniversalObject.imageUrl = @"https://example.com/mycontent-12345.png";
branchUniversalObject.contentMetadata.contentSchema = BranchContentSchemaCommerceProduct;
branchUniversalObject.contentMetadata.customMetadata[@"property1"] = @"blue";
branchUniversalObject.contentMetadata.customMetadata[@"property2"] = @"red";
Swift
let branchUniversalObject: BranchUniversalObject = BranchUniversalObject(canonicalIdentifier: "item/12345")
branchUniversalObject.title = "My Content Title"
branchUniversalObject.contentDescription = "My Content Description"
branchUniversalObject.imageUrl = "https://example.com/mycontent-12345.png"
branchUniversalObject.contentMetadata.contentSchema = .product;
branchUniversalObject.contentMetadata.customMetadata["property1"] = "blue"
branchUniversalObject.contentMetadata.customMetadata["property2"] = "red"

属性

canonicalIdentifier :这是内容的唯一标识,可帮助 Branch 在同一事物的许多实例之间进行重复数据删除。如果您的网站带有路径,请随时使用它。或者,如果您有实体的数据库唯一标识,请使用这些唯一标识。

title :这是内容的名称,将自动用于 OG 标签。它将$og_title 插入到创建的任何链接的数据字典中。

contentDescription :这是内容的描述,将自动用于 OG 标签。它将$og_description 插入到创建的任何链接的数据字典中。

imageUrl :这是内容的图像 URL,将自动用于 OG 标签。它将$og_image_url 插入到创建的任何链接的数据字典中。

keywords :描述对象的关键字。这些用于 Spotlight 搜索和 Web 抓取,以便用户可以找到您的内容。

localIndex :如果设置为 true,则 Branch 将在用户手机的Spotlight 上为该内容编制索引。

publiclyIndex :如果设置为 true,则 Branch 将在 Google,Branch 等将该内容编入索引。

expirationDate :内容不再可用或有效的日期。当前,此功能仅用于 Spotlight 索引编制,但将来可被 Branch 使用。

contentMetadata :进一步描述内容的详细信息。根据与您的内容相关的内容类型设置此子对象的属性:

BranchUniversalObject.contentMetadata

BranchUniversalObject.contentMetadata 属性进一步描述了您的内容。这些属性可在 Branch 操作后台 (Dashboard)追踪,并将自动导出到相连接的第三方应用程序智能合作伙伴,如 Adjust 或 Mixpanel。

根据与您的内容相关的内容类型设置此子对象的属性。 BranchUniversalObject.contentMetadata.contentSchema 属性描述对象内容的类型。设置其他与类型相关的属性。

contentMetadata.contentSchema :将此属性设置为BranchContentSchema 最能描述内容类型的枚举。它接受BranchContentSchemaCommerceProductBranchContentSchemaMediaImage类的值。

contentMetadata.customMetadata :此词典包含您想要与 Branch Universal Object 关联的所有其他参数。用户点击链接并打开应用程序后,即可使用这些功能。

contentMetadata.price :与以下和 commerce 相关事件结合使用的商品价格。

contentMetadata.currency :以 ISO 4217货币代码表示价格的货币。默认值为美元。

contentMetadata.quantity :数量。

contentMetadata.sku :供应商 SKU。

contentMetadata.productName :产品名称。

contentMetadata.productBrand :产品品牌。

contentMetadata.productCategory BNCProductCategory 值,例如BNCProductCategoryAnimalSuppliesBNCProductCategoryFurniture

contentMetadata.productVariant :产品变体。

contentMetadata.condition BranchCondition 值,例如BranchConditionNewBranchConditionRefurbished

ratingAverage,ratingCount,ratingMax :对您的内容的评分。

addressStreet,addressCity,addressRegion,addressCountry,addressPostalCode :您的内容地址。

经度,纬度 :内容的经度和纬度。

imageCaptions :内容图像的图像标题。

追踪与对象的用户交互

我们已经添加了一系列自定义事件,您想要开始追踪这些事件,以进行丰富的分析和定位。以下是带有调用注册视图事件的示例代码片段的列表。

BranchStandardEventViewItem用户查看了对象
BranchStandardEventAddToWishlist用户将该对象添加到他们的愿望清单
BranchStandardEventAddToCart用户将对象添加到购物车
BranchStandardEventInitiatePurchase用户开始签出
BranchStandardEvent购买用户购买了该物品
BranchStandardEventShare用户完成了分享

方法

Objective-C
[branchUniversalObject userCompletedAction:BranchStandardEventViewItem];
Swift
branchUniversalObject.userCompletedAction(BranchStandardEventViewItem)

参量

退货

缩短链接

一旦创建了Branch Universal Object ,即对感兴趣的内容的引用,您则可以使用下面描述的机制获得返回到该内容的链接。

编码说明

关于编码的简要说明。由于NSJSONSerialization支持一组有限的类,因此我们进行一些自定义编码以允许额外类型。当前支持的类型包括NSDictionaryNSArrayNSURLNSStringNSNumberNSNullNSDate (编码为带时区 ISO8601 string )。如果参数的类型未知,它将被忽略。

方法

Objective-C
#import "BranchLinkProperties.h"
BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
linkProperties.channel = @"facebook";
[linkProperties addControlParam:@"$desktop_url" withValue:@"http://example.com/home"];
[linkProperties addControlParam:@"$ios_url" withValue:@"http://example.com/ios"];
[branchUniversalObject getShortUrlWithLinkProperties:linkProperties andCallback:^(NSString *url, NSError *error) {
    if (!error) {
        NSLog(@"success getting url! %@", url);
    }
}];
Swift
let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.feature = "sharing"
linkProperties.channel = "facebook"
linkProperties.addControlParam("$desktop_url", withValue: "http://example.com/home")
linkProperties.addControlParam("$ios_url", withValue: "http://example.com/ios")
branchUniversalObject.getShortUrl(with: linkProperties) { (url, error) in
    if error == nil {
        NSLog("got my Branch link to share: %@", url)
    }
}

链接属性参数

channel :链接的渠道。示例有 Facebook,Twitter,短信等,具体取决于共享位置。

feature :与生成的链接相关联的功能。例如, sharing

controlParams :建立 Branch Link 时要使用的字典。您可以在此处指定自定义行为控件,如下表所述。

您可以通过在字典插入以下可选 key 来进行自定义重定向:

"$fallback_url"未安装应用程序时将所有平台的用户发送到此。请注意,Branch 会将所有 robots 转发到此 URL,从而覆盖在链接中输入的所有 OG 标签。
"$desktop_url"在台式机或笔记本电脑上发送用户处。默认情况下,它是 Branch 托管的 text-me 服务。
"$android_url"Play Store 的替代 URL,用于在用户没有该应用的情况下向其发送。只有当您想要移动网页启动时才需要它
"$ios_url"App Store 的替代 URL,用于在用户没有该应用的情况下向其发送。只有当您想要移动网页启动时才需要它
"$ipad_url"与上述相同,但适用于 iPad Store。
"$fire_url"与上述相同,但适用于 Amazon Fire Store。
"$blackberry_url"与上述相同,但适用于 Blackberry Store。
"$windows_phone_url"与上述相同,但适用于 Windows Store。
"$after_click_url"当用户转到应用程序后返回浏览器时,将其带到该 URL。仅限 iOS; Android 版即将面世

通过在字典插入以下可选 key,您可以控制每个链接的直接深度链接:

"$deeplink_path"您希望我们追加到您的 URI 的深度链接路径的值。例如,您可以指定 "$deeplink_path": "radio/station/456",然后我们将使用 URI "yourapp://radio/station/456?link_click_id=branch-identifier" 打开应用程序。这主要是为了支持旧版深度链接基础架构。
"$always_deeplink"true 或 false。 (默认设置为不先进行深度链接)即使我们不确定用户是否已安装该应用程序,也可以指定此 key 以使我们的链接服务团队尝试打开该应用程序。如果未安装该应用程序,我们将退回到相应的 app store 或 $platform_url key。默认情况下,我们仅在看到用户通过 Branch Link 在您的应用中启动会话(已被 Branch cookie 并进行深度链接)时才会打开该应用。

alias :链接的别名。例如, myapp.com/customalias

matchDuration :来自链接点击的归因窗口(以秒为单位)。

stage :用于生成链接的阶段,指示用户位于漏斗的哪个部分。

tags :与链接关联的标签 string 数组。

获取简短 URL 参数

linkProperties :上面创建的链接属性,用于描述您想要的链接类型

callback :成功使用 url 调用的回调,亦或是一个错误(如出现问题)。请注意,我们会100%返回链接。如果网络可用,则是一个短链接;如果网络不可用,则是一个长链接。

UIActivityView 共享表

UIActivityView 是允许用户共享来自应用程序的内容的标准方法。一旦创建了Branch Universal Object ,即对您感兴趣的内容的引用,您则可以自动将其共享而无需使用以下机制创建链接

示例 UIActivityView 共享表

UIActivityView 共享表UIActivityView 共享表

Branch iOS SDK 在 UIActivityViewController 上包含一个包装器,该包装器将生成 Branch 短 URL,并使用用户选择的渠道(Facebook,Twitter 等)自动对其进行标记。请注意,某些渠道限制对某些字段的访问。例如,Facebook 禁止您预填充消息。

方法

Objective-C
#import "BranchLinkProperties.h"
BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
[linkProperties addControlParam:@"$desktop_url" withValue:@"http://example.com/home"];
[linkProperties addControlParam:@"$ios_url" withValue:@"http://example.com/ios"];
[branchUniversalObject showShareSheetWithLinkProperties:linkProperties
                                           andShareText:@"Super amazing thing I want to share!"
                                     fromViewController:self
                                             completion:^(NSString *activityType, BOOL completed){
    NSLog(@"finished presenting");
}];
Swift
let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.feature = "sharing"
linkProperties.addControlParam("$desktop_url", withValue: "http://example.com/home")
linkProperties.addControlParam("$ios_url", withValue: "http://example.com/ios")
branchUniversalObject.showShareSheet(with: linkProperties,
                                     andShareText: "Super amazing thing I want to share!",
                                     from: self) { (activityType, completed) in
    NSLog("done showing share sheet!")
}

显示共享表参数

linkProperties :与生成的链接相关联的功能。

andShareText :建立 Branch Link 时使用的字典。

fromViewController

completion

进一步定制

大多数共享选项仅包含一串文本,但电子邮件除外,该电子邮件具有主题和正文。共享文本将填充在正文中,您可以在链接属性中指定电子邮件主题,如下所示。

[linkProperties addControlParam:@"$email_subject" withValue:@"This one weird trick."];
linkProperties.addControlParam("$email_subject", withValue: "Therapists hate him.")

您还可以选择将 HTML 添加到电子邮件选项并自定义链接文本。如果省略了链接文本,则使用 url 本身

[linkProperties addControlParam:@"$email_html_header" withValue:@"<style>your awesome CSS</style>\nOr Dear Friend,"];
[linkProperties addControlParam:@"$email_html_footer" withValue:@"Thanks!"];
[linkProperties addControlParam:@"$email_html_link_text" withValue:@"Tap here"];
linkProperties.addControlParam("$email_html_header", withValue: "<style>your awesome CSS</style>\nOr Dear Friend,")
linkProperties.addControlParam("$email_html_footer", withValue: "Thanks!")
linkProperties.addControlParam("$email_html_link_text", withValue: "Tap here")

快速更改共享文本

您可以根据用户在共享表活动中所做的选择来更改链接 shareText 和其他链接参数。首先,用遵循BranchShareLinkDelegate协议的对象设置BranchShareLink委托。

可选的- (void) branchShareLinkWillShare:委托方法将在用户选择共享操作之后(例如,通过电子邮件共享),并在向用户显示共享操作之前(例如,将电子邮件编辑器与共享文本一起显示给用户时)调用文本。这是根据用户操作更改共享文本的理想时间。

用户完成共享操作后,将调用可选的- (void) branchShareLink:didComplete:withError:委托方法。如果用户共享项目,则didComplete布尔值将为YES ,如果用户取消则为NOerror值将指示可能发生的任何错误。

Objective-C
@interface ViewController () <BranchShareLinkDelegate>

覆盖 branchShareLinkWillShare 函数以更改您的 shareText

- (void) branchShareLinkWillShare:(BranchShareLink*)shareLink {
    // Link properties, such as alias or channel can be overridden here based on the users'
    // choice stored in shareSheet.activityType.
    shareLink.shareText = [NSString stringWithFormat:
        @"Shared through '%@'\nfrom Branch's Branch-TestBed\nat %@.",
        shareLink.linkProperties.channel,
        [self.dateFormatter stringFromDate:[NSDate date]]];
}
Swift
class ViewController: UITableViewController, BranchShareLinkDelegate

覆盖 branchShareLinkWillShare 函数以更改您的 shareText

func branchShareLinkWillShare(_ shareLink: BranchShareLink) {
    // Link properties, such as alias or channel can be overridden here based on the users'
    // choice stored in shareSheet.activityType.
    shareLink.shareText =
        "Shared through '\(shareLink.linkProperties.channel!)'\nfrom Branch's TestBed-Swift" +
        "\nat \(self.dateFormatter().string(from: Date()))."
}

退货

在 Spotlight 上列出内容

如果您想在 Spotlight 本地索引和云索引中列出您的 Branch Universal Object,这就是您要调用的方法。您需要在每次页面加载时注册视图,因为这有助于您在搜索中的全球排名。

方法

Objective-C
branchUniversalObject.automaticallyListOnSpotlight = YES;
[branchUniversalObject userCompletedAction:BranchStandardEventViewItem];
Swift
branchUniversalObject.automaticallyListOnSpotlight = true
branchUniversalObject.userCompletedAction(BranchStandardEventViewItem)

参量

callback :如果您想存储为自己的记录,则将返回用于在 Spotlight 中列出内容的 URL。

退货

使用链接属性在 Spotlight 上列出内容

如果要在 Spotlight 本地索引和云索引中列出带有链接属性的 Branch Universal Object,则将使用此方法。您需要在每次页面加载时注册视图,因为这有助于您在搜索中的全球排名。

方法

Objective-C
[universalObject listOnSpotlightWithLinkProperties:linkProperties callback:^(NSString * _Nullable url, NSError * _Nullable error) {
    if (!error) {
         NSLog(@"Successfully indexed on spotlight");
    }
}];
Swift
universalObject.listOnSpotlight(with: linkProperty) { (url, error) in
    if (error == nil) {
        print("Successfully indexed on spotlight")
    }
}

参量

callback :如果您想存储为自己的记录,则将返回用于在 Spotlight 中列出内容的 URL。

退货

使用 CSSearchableIndex 在 Spotlight 上列出多个Branch Universal Object

在 Branch 共享实例上调用此方法以在 Spotlight 中列出多个 Branch Universal Object:

方法

Objective-C
[[Branch getInstance] indexOnSpotlightUsingSearchableItems:universalObjects
                                                    completion:^(NSArray<BranchUniversalObject *> *universalObjects,
                                                                 NSError *error) {
        if (!error) {
            // Successfully able to index all the BUO on spotloght
        }
    }];
Swift
Branch.getInstance().indexOnSpotlight(usingSearchableItems: universalObjects,
                                                completion: { (universalObjects, error) in
      if (error) {
           // Successfully able to index all the BUO on spotloght
      }
})

参量

UniversalObjects :将使用CSSearchableIdex索引的所有 Branch Universal Object 的数组

completion:索引完成时,将返回带有动态 URL 的 Branch Universal Object 作为 Spotlight 唯一标识。

退货

如果已私有索引,则从 Spotlight 中删除 Branch Universal Object

私有索引的 Branch Universal Object 可从 Spotlight 中删除

方法

Objective-C
[universalObject removeFromSpotlightWithCallback:^(NSError * _Nullable error) {
        if (!error) {
            NSLog(@"universal Object removed from spotlight");
        }
    }];
Swift
universalObject.removeFromSpotlight { (error) in
            if(error == nil) {
                print("BUO successfully removed")
            }
        }

参量

Callback:将 Branch Universal Object 从 Spotlight 移除后返回。如果移除了Spotlight,则 Branch Universal Object 的 spotlightIdentifier 变量将为 nil。

退货

如果已私有索引,则从 Spotlight 中删除多个 Branch Universal Object

私有索引的多个 Branch Universal Object 可从 Spotlight 中删除

方法

Objective-C
[[Branch getInstance] removeSearchableItemsWithBranchUniversalObjects:@[BUO1,BUO2] callback:^(NSError *error) {
    if (!error) {
        NSLog(@"An array of BUOs removed from spotlight");
    }
}]

Swift
Branch.getInstance().removeSearchableItems(with: [BUO1,BUO2]) { (error) in
    if (error == nil) {
        print("An array of BUOs removed from spotlight")
    }
}

参量

Callback:将 Branch Universal Object 从 Spotlight 移除后返回。如果移除了Spotlight,则 Branch Universal Object 的 spotlightIdentifier 变量将为 nil。

退货

如果已私有索引,则从 Spotlight 中删除所有 Branch Universal Object

私有索引的所有 Branch Universal Object 可从 Spotlight 中删除

方法

Objective-C
[[Branch getInstance] removeAllPrivateContentFromSpotLightWithCallback:^(NSError *error) {
    if (!error) {
      NSLog(@"All branch privately indexed content removed from spotlight");
    }
}];
Swift
Branch.getInstance().removeAllPrivateContentFromSpotLight { (error) in
    if (error == nil) {
        print("All branch privately indexed content removed from spotlight")
    }
}

参量

回调 :一旦将所有“分支通用对象”从聚光灯中移除,将返回。
注意:SpotlightIdentifer不会成为所有从Spotlight中删除的分支通用对象的零,因为Branch SDK不缓存分支通用对象。

退货

推荐系统奖励功能

获得奖励余额

当采取某些操作(由您的规则定义)时,奖励余额在后端随机变化,因此您需要进行异步调用来检索余额。语法如下:

方法

Objective-C
[[Branch getInstance] loadRewardsWithCallback:^(BOOL changed, NSError *error) {
    // changed boolean will indicate if the balance changed from what is currently in memory

    // will return the balance of the current user's credits
    NSInteger credits = [[Branch getInstance] getCredits];
}];
Swift
Branch.getInstance().loadRewards { (changed, error) in
    // changed boolean will indicate if the balance changed from what is currently in memory

    // will return the balance of the current user's credits
    let credits = Branch.getInstance().getCredits()
}

参量

callback :请求完成后调用的回调。

兑换全部或部分奖励余额(Store 状态)

兑换积分可以使用户兑现所获得的积分。成功兑换后,用户余额将更新以反映扣除额。

方法

Objective-C
// Save that the user has redeemed 5 credits
[[Branch getInstance] redeemRewards:5];
Swift
// Save that the user has redeemed 5 credits
Branch.getInstance().redeemRewards(5)

参量

amount :兑换的积分数。

获取积分记录

该调用将检索单个用户的积分和兑换的整个历史记录。要使用此调用,请按照如下方法实现:

方法

Objective-C
[[Branch getInstance] getCreditHistoryWithCallback:^(NSArray *history, NSError *error) {
    if (!error) {
        // process history
    }
}];
Swift
Branch.getInstance().getCreditHistory { (creditHistory, error) in
    if error == nil {
        // process history
    }
}

Response 将返回一个已从以下 JSON 解析的数组:

[
    {
        "transaction": {
                           "date": "2014-10-14T01:54:40.425Z",
                           "id": "50388077461373184",
                           "bucket": "default",
                           "type": 0,
                           "amount": 5
                       },
        "event" : {
            "name": "event name",
            "metadata": { your event metadata if present }
        },
        "referrer": "12345678",
        "referree": null
    },
    {
        "transaction": {
                           "date": "2014-10-14T01:55:09.474Z",
                           "id": "50388199301710081",
                           "bucket": "default",
                           "type": 2,
                           "amount": -3
                       },
        "event" : {
            "name": "event name",
            "metadata": { your event metadata if present }
        },
        "referrer": null,
        "referree": "12345678"
    }
]

参量

推荐人
此信贷交易的推荐用户的ID。如果不涉及引荐来源,则返回null。请注意,此ID是开发人员自己的系统中的用户ID,之前已传递给Branch的标识用户API调用。

裁判
此信用交易被引荐的用户的ID。如果不涉及裁判,则返回null。请注意,此ID是开发人员自己的系统中的用户ID,之前已传递给Branch的标识用户API调用。

类型
这是信贷交易的类型。

  1. 0—完成动作或促销的用户自动添加的奖励。
  2. 1-手动添加的奖励。
  3. 2-通过我们的API或SDK兑换积分。
  4. 3—这是一种非常特殊的情况,当我们检测到欺诈行为时,我们将自动扣除积分。

5个月前更新


iOS完整参考


建议的编辑仅限于API参考页

您只能建议对Markdown正文内容进行修改,而不能建议对API规范进行修改。