macOS 高级功能

开启记录

为了帮助调试应用，您可以打开 Branch 日志记录，该日志记录到控制台。请记住在生产应用中将其关闭。

属性

Branch.loggingIsEnabled

Branch.loggingEnabled

设置用户身份

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

方法

private func login(userIdentity: String?) {
        guard let userIdentity = userIdentity else { return }

        Branch.sharedInstance.setUserIdentity(userIdentity,
                                              completion: { (branchSession, error) in
                                                // Do stuff with login
                                              })
    }

[Branch setUserIdentity:completion:]

参见 setUserIdentity:completion:

Get User Identity

Use the getUserIdentity method to retrieve the user ID set via setUserIdentity。

方法

var userIdentity = Branch.sharedInstance().getUserIdentity()

NSString *userIdentity = [Branch sharedInstance].getUserIdentity();

参见 getUserIdentity

注销

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

🚧
警告
This call will clear attribution on the device.

方法

private func logout() {
        Branch.sharedInstance.logout(completion: { (error) in
          // Do stuff on logout
        })
    }

[Branch logoutWithCompletion:]

参见 logoutWithCompletion:

追踪用户操作和事件

Use the BranchEvent class to track special user actions or application specific events beyond app installs, opens, and sharing. You can track events such as when a user adds an item to an on-line shopping cart, or searches for a keyword, among others.

The BranchEvent interface provides an interface to add contents represented by BranchUniversalObject in order to associate app contents with events.

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

The BranchEvent class can be simple to use. For example:

Branch.sharedInstance.logEvent(.standardEvent(.addToCart))

[[Branch sharedInstance]
    logEvent:[BranchEvent standardEvent:BranchStandardEventAddToCart]];

For best results use the Branch standard event names defined in BranchEvent.h. But you can use your own custom event names too:

Branch.sharedInstance.logEvent(.customEvent(withName: "User_Scanned_Item"))

[[Branch sharedInstance]
    logEvent:[BranchEvent customEventWithName:@"User_Scanned_Item"]];

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

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"
]
Branch.sharedInstance.logEvent(event)

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"
};
[[Branch sharedInstance] logEvent: event];

启用或禁用用户追踪

如果您需要按照 GDPR 的目的遵循用户不被追踪的请求，或者认为用户不应该被追踪，请利用此字段来防止 Branch 发送网络请求。此设置也可以在所有用户的特定链接或 Branch Link 中被启用。

Branch.sharedInstance().trackingDisabled = true

[Branch sharedInstance].trackingDisabled = YES;

您可以选择在应用的整个生命周期中调用它。调用后，网络请求将不会从 SDK发送。链接生成将继续起作用，但是不会包含有关用户的标识信息。此外，深度链接将继续起作用，但不会为用户追踪分析。

设置初始化 metadata

🚧
仅限数据集成

If you are using a 3rd Party Data Integration Partner that requires setting certain identifiers before initializing the Branch SDK, you should add this code snippet:

let dict = NSMutableDictionary()
        dict.setObject("your metadata" as NSString, forKey: "sample_key" as NSString)
        Branch.sharedInstance.requestMetadataDictionary = dict

NSMutableDictionary<NSString *, NSString *> *metadata = [NSMutableDictionary<NSString *, NSString *> new];
    [metadata setObject:@"your metadata" forKey:@"sample_key"];
    [[Branch sharedInstance] setRequestMetadataDictionary:metadata];

Branch Universal Object

使用 BranchUniversalObject 来描述应用中的内容，以进行深度链接，内容分析和索引。

属性对象以标准方式描述您的内容，例如
可以在 Spotlight 上进行深度链接，分享或建立索引。您可以设置与对象关联的所有属性，然后对其调用操作方法以在 Spotlight 上创建链接或内容索引
。

Branch Universal Object 最佳实践

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

将 canonicalIdentifier to a unique, de-duped value across instances of the app
请确保 title， contentDescription and imageUrl properly represent the object
Call showShareSheet and createShortLink later in the life cycle, when the user takes an action that needs a link
当采取相应的用户操作时，调用其他对象事件（购买，分享完成等）
将 contentIndexMode to ContentIndexModePublic or ContentIndexModePrivate. If BranchUniversalObject is set to ContentIndexModePublic, then content would indexed using NSUserActivity, or else content would be index using CSSearchableIndex on Spotlight.

📘
注意
Content indexed using CSSearchableItem could be removed from Spotlight but cannot be removed if indexed using NSUserActivity。

🚧
Practices to Avoid

Don't set the same title， contentDescription and imageUrl across all objects.

请不要等到用户分享再初始化对象并注册视图。

请不要等到您需要链接再初始化对象。

Don't create many objects at once and register views in a for loop.

方法

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"

#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";

属性

属性	描述
canonicalIdentifier	这是内容的标识符，可帮助 Branch 在同一事物的许多实例之间进行重复数据删除。如果您的网站带有路径，请随时使用。或者，如果您具有实体的数据库标识符，请使用这些。
标题	This is the name for the content and will automatically be used for the OG tags. It will insert `$og_title` into the data dictionary of any link created.
contentDescription	This is the description for the content and will automatically be used for the OG tags. It will insert `$og_description` into the data dictionary of any link created.
imageUrl	This is the image URL for the content and will automatically be used for the OG tags. It will insert `$og_image_url` into the data dictionary of any link created.
关键字	描述对象的关键字。这些用于 Spotlight 搜索和 Web 抓取，以便用户可以找到您的内容。
locallyIndex	If set to true, Branch will index this content on Spotlight on the user's mac.
publiclyIndex	如果设置为 true，则 Branch 将在 Google，Branch 等为该内容编制索引。
expirationDate	内容将不再可用或有效的日期。目前，此功能仅用于 Spotlight 索引编制，但将来会被 Branch 使用。
contentMetadata	Details that further describe your content. Set the properties of this sub-object depending on the type of content that is relevant to your content. See table below BranchUniversalObject.contentMetadata

BranchUniversalObject.contentMetadata

The BranchUniversalObject.contentMetadata properties further describe your content. These properties are trackable in the Branch dashboard and will be automatically exported to your connected third-party app intelligence partners like Adjust or Mixpanel.

Set the properties of this sub-object depending on the type of content that is relevant to your content. The BranchUniversalObject.contentMetadata.contentSchema property describes the type of object content. Set other properties as is relevant to the type.

属性	描述
contentMetadata.contentSchema	Set this property to a `BranchContentSchema` enum that best describes the content type. It accepts values like `BranchContentSchemaCommerceProduct` and `BranchContentSchemaMediaImage`。
contentMetadata.customMetadata	该词典包含您希望与 Branch Universal Object 相关的所有其他参数。用户点击链接并打开应用后，即可使用这些功能。
contentMetadata.price	与以下 commerce 相关事件结合使用的商品价格。
contentMetadata.currency	The currency representing the price in ISO 4217 currency code. The default is USD.
contentMetadata.quantity	数量。
contentMetadata.sku	供应商 SKU。
contentMetadata.productName	产品名称。
contentMetadata.productBrand	产品品牌。
contentMetadata.productCategory	The `BNCProductCategory` value, such as `BNCProductCategoryAnimalSupplies` or `BNCProductCategoryFurniture`。
contentMetadata.productVariant	产品变体。
contentMetadata.condition	The `BranchCondition` value, such as `BranchConditionNew` or `BranchConditionRefurbished`。
ratingAverage, ratingCount, ratingMax	内容的评分。
addressStreet, addressCity, addressRegion, addressCountry, addressPostalCode	内容的地址。
latitude, longitude	内容的经度和纬度。
imageCaptions	内容图像的图像标题。

追踪用户操作和事件

我们已经添加了一系列您希望开始追踪的自定义事件，以便使您进行丰富的分析和定位。下面的列表列出了一个示例片段，该片段调用了注册视图事件。

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

方法

branchUniversalObject.logEvent(BranchStandardEventViewItem)

[branchUniversalObject userCompletedAction:BranchStandardEventViewItem];

参数

无

Returns

无

缩短链接

Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then get a link back to it with the mechanisms described below.

📘
编码说明
One quick note about encoding. Since NSJSONSerialization supports a limited set of classes, we do some custom encoding to allow additional types. Current supported types include NSDictionary， NSArray， NSURL， NSString， NSNumber， NSNull, and NSDate (encoded as an ISO8601 string with timezone). If a parameter is of an unknown type, it will be ignored.

方法

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)
    }
}

#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);
    }
}];

链接属性参数

参数	描述
渠道	链接的渠道。示例可以为 Facebook，Twitter，短信等，具体取决于分享位置。
功能	The feature the generated link will be associated with, e.g., `sharing`。
controlParams	建立 Branch Link 时要使用的字典。您可以在此处指定自定义行为控件，如下表所述。

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

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 版即将面世。
`$afterclick_desktop_url`	当桌面上的用户转到桌面应用后返回桌面浏览器时，将其带到该 URL。

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

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	The alias for a link, e.g., `myapp.com/customalias`
matchDuration	来自链接的点击归因窗口（以秒为单位）。
阶段	用于生成链接的阶段，指示用户位于漏斗的哪个部分。
标签	与链接相关的 tag string 数组。

获取简短 URL 参数

参数	描述
linkProperties	上面创建的链接属性，描述了您想要的链接类型
linkProperties	成功时使用 url 调用的回调，如果出现问题则返回错误。请注意，我们会以100％的概率返回链接。如果网络可用，则会是一个短链接；如果网络不可用，则会是一个长链接。

Create QR Code

Create a BranchUniversalObject and BranchLinkProperties
Create a BranchQRCode object and set the properties
Use getQRCodeAsImage() or getQRCodeAsData() to create a QR code

BranchLinkProperties *linkProperties = [BranchLinkProperties new];
    BranchUniversalObject *buo = [BranchUniversalObject new];
    
    BranchQRCode *qrCode = [BranchQRCode new];
    qrCode.codeColor = [NSColor colorWithCalibratedRed:0.1 green:0.8392 blue:1.0 alpha:1.0f];
    qrCode.backgroundColor = NSColor.whiteColor;
    qrCode.width = @500;
    qrCode.margin = @1;
    qrCode.centerLogo = @"https://cdn.branch.io/branch-assets/1598575682753-og_image.png";
    qrCode.imageFormat = BranchQRCodeImageFormatPNG;
    
    [qrCode getQRCodeAsImage:buo linkProperties:linkProperties completion:^(CIImage * _Nullable qrCodeImage, NSError * _Nullable error) {
        //Use the QR code image here...
    }];

macOS 高级功能

开启记录

属性

设置用户身份

方法

Get User Identity

方法

注销

🚧
警告

方法

追踪用户操作和事件

启用或禁用用户追踪

设置初始化 metadata

🚧
仅限数据集成

Branch Universal Object

Branch Universal Object 最佳实践

📘
注意

🚧
Practices to Avoid

方法

属性

BranchUniversalObject.contentMetadata

追踪用户操作和事件

方法

参数

Returns

缩短链接

📘
编码说明

方法

链接属性参数

获取简短 URL 参数

Create QR Code

筛选项

开启记录

属性

设置用户身份

方法

Get User Identity

方法

注销

🚧警告

方法

追踪用户操作和事件

启用或禁用用户追踪

设置初始化 metadata

🚧仅限数据集成

Branch Universal Object

Branch Universal Object 最佳实践

📘注意

🚧Practices to Avoid

方法

属性

BranchUniversalObject.contentMetadata

追踪用户操作和事件

方法

参数

Returns

缩短链接

📘编码说明

方法

链接属性参数

获取简短 URL 参数

Create QR Code

🚧
警告

🚧
仅限数据集成

📘
注意

🚧
Practices to Avoid

📘
编码说明