Jointag Proximity SDK 文档

安装

CocoaPods安装

安装或更新到版本 1.9.0或更高版本 的 CocoaPods，这对于正确支持新的 xcframework 格式至关重要。
在终端中，从项目目录执行 pod init，如果项目尚未启用 Pod。
编辑您的项目 Podfile 并将 pod 'JTProximitySDK' 添加到主应用程序目标中。
在终端中，从项目目录执行 pod install。

例如

target 'MyApp' do
  use_frameworks!
  pod 'JTProximitySDK'
end

有关更多信息，请参阅CocoaPods。

手动安装

Jointag Proximity SDK 以编译的 xcframework 格式分发，包含针对设备和模拟器的二进制文件。要将它添加到您的项目中，请按照以下步骤包含 JTProximitySDK.xcframework

将 JTProximitySDK.xcframework 框架文件夹拖放到 Xcode 项目中（记得勾选 "Copy items if needed"）。
确保 JTProximitySDK.xcframework 出现在项目的 General 选项卡的 Frameworks, Libraries, and Embedded Content 部分中，并且 embed 模式是 Embed & Sign。

权限和服务

以下部分描述了 SDK 所需的权限，以及必须添加到应用程序 Info.plist 文件中的必要密钥。

⚠️注意：从 SDK 版本 1.12.0 开始，在启动 SDK 时不再自动请求所有必需的权限，而必须由应用程序自身请求用户。为了简化此过程，SDK 提供了帮助方法来实现请求（以下将介绍这些方法）。

用户跟踪权限

如同这里所述，用户跟踪权限需要在应用程序的 Info.plist 文件中添加以下密钥

<key>NSUserTrackingUsageDescription</key>
<string>User Tracking Usage Description</string>

提供了帮助方法，可以轻松请求跟踪授权

Swift

Proximity.shared.requestTrackingAuthorization()

Objective-C

[JTProximitySDK.sharedInstance requestTrackingAuthorization];

通知权限

提供了一个辅助方法，可以轻松地请求通知授权

Swift

Proximity.shared.requestNotificationAuthorization()

Objective-C

[JTProximitySDK.sharedInstance requestNotificationAuthorization];

位置权限

如描述此处，用户位置权限需要在应用的Info.plist文件中添加以下键

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location usage description</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location usage description</string>

提供了一个辅助方法，可以轻松地请求位置授权

Objective-C

[JTProximitySDK.sharedInstance requestLocationAuthorization];

Swift

Proximity.shared.requestLocationAuthorization()

设置

初始化SDK

将以下代码放置在应用的UIApplicationDelegate中

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [JTProximitySDK.sharedInstance initWithLaunchOptions:launchOptions apiKey:@"YOUR_API_KEY" apiSecret:@"YOUR_API_SECRET"];
    // Other application logics
}

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    ProximitySDK.shared.initWithLaunchOptions(launchOptions, apiKey: "YOUR_API_KEY", apiSecret: "YOUR_API_SECRET")
    // Other application logics
    return true
}

iOS 13场景

如果您的应用使用了iOS 13场景，还需满足额外要求：将SDK的windowSceneDelegate引用更新为当前的active UIWindowSceneDelegate。

为此，您必须将以下代码添加到当前的UIWindowSceneDelegate的scene:willConnectToSession:options:

Swift

import UIKit
import JTProximitySDK

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        ProximitySDK.shared.windowSceneDelegate = self
        guard let _ = (scene as? UIWindowScene) else { return }
    }
}

处理通知

为了使SDK能够正确发送和管理广告通知，您必须在您的UNUserNotificationCenterDelegate中实现以下方法：

Objective-C

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler __IOS_AVAILABLE(10.0) {
    if ([JTProximitySDK.sharedInstance userNotificationCenter:center willPresentNotification:notification]) {
        completionHandler(UNNotificationPresentationOptionAlert|UNNotificationPresentationOptionBadge|UNNotificationPresentationOptionSound);
        return;
    }
    // Other application logics
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler __IOS_AVAILABLE(10.0) {
    if ([JTProximitySDK.sharedInstance userNotificationCenter:center didReceiveNotificationResponse:response]) {
        completionHandler();
        return;
    }
    // Other application logics
}

Swift

@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    if ProximitySDK.shared.userNotificationCenter(center, willPresent: notification) {
        completionHandler([.alert, .badge, .sound])
        return
    }
    // Other application logics
}

@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    if ProximitySDK.shared.userNotificationCenter(center, didReceive: response) {
        completionHandler()
        return
    }
    // Other application logics
}

⚠️注意：许多第三方推送通知库采用完全替换默认的UNUserNotificationCenterDelegate或对当前代理的方法进行swizzle的做法。在这种情况下，您会发现正常的代理方法没有被调用，并且Jointag Proximity SDK将不会显示或打开靠近通知。

通常，具有这种类型实现的库提供接收所需事件的替代方法。

如果您的这情况，请仔细阅读第三方库文档以了解如何通过它们的库来实现上述方法。

高级配置

跟踪用户标识符

广告ID和安装ID

SDK将每个跟踪请求与advertisingId相关联。如果由于用户权限拒绝，无法获取advertisingId，则可以使用installationId来识别设备。该installationId是在第一次初始化期间随机生成的UUID，因此可以识别该应用程序的SDK的具体安装。如果包含SDK的应用程序被卸载然后重新安装，则installationId将是不同的。您可以在代码中通过以下行检索installationId：

Objective-C

JTProximitySDK.sharedInstance.installationId;

Swift

ProximitySDK.shared.installationId()

外部用户ID

externalUserId是一个标识符，您可以用它来将您选择的唯一用户标识符与我们的installationId配对。提示：通常，在用户登录到您的应用程序之后设置此标识符，并在用户决定从应用程序中注销后删除此标识符。

您可以选择任意长度不超过255个字符的字符串作为externalUserId。

您的externalUserId可以与多个installationId配对，例如，如果同一个用户在多个设备上使用您的应用程序，或者同一个用户多次卸载和安装您的应用程序。

另一方面，相同的安装ID可以与一个且仅与一个外部用户ID关联，通常是最后发送的那个。

例如，您可以使用您的数据库或CRM的用户记录ID，或电子邮件地址的哈希值，或第三方平台标识符。

使用setExternalUserId方法添加您独特的用户ID

Objective-C

// Set
[JTProximitySDK.sharedInstance setExternalUserId: @"SOME ID"];
// Unset
[JTProximitySDK.sharedInstance setExternalUserId: nil];

Swift

// Set
ProximitySDK.shared.externalUserId = "SOME ID"
// Unset
ProximitySDK.shared.externalUserId = nil

数据标签

标签是自定义的键值对，类型为字符串、数字、布尔值或NSNull，可以通过SDK方法发送到我们的服务器，从而允许您更有效地定位广告活动，或者根据用户的特征接收个性化的分析。

可以使用以下方法设置或取消设置（使用null 值）标签

sendTag

sendTag方法允许一次设置或取消设置一个标签。

该方法可以多次调用。当发送不同的键时，其效果是累积的。如果使用相同的键，则最后一个值会覆盖之前的值。

Objective-C

[JTProximitySDK.sharedInstance sendTag: @"value" forKey: "key1"];
// -> { "key1" : "value" }
[JTProximitySDK.sharedInstance sendTag:@1 forKey:@"key2"];
// -> { "key1" : "value", "key2" : 1 }
[JTProximitySDK.sharedInstance sendTag:@YES forKey:@"key3"];
// -> { "key1" : "value", "key2" : 1, "key3" : true }
[JTProximitySDK.sharedInstance sendTag:@NO forKey:@"key3"];
// -> { "key1" : "value", "key2" : 1, "key3" : false }
[JTProximitySDK.sharedInstance sendTag:nil forKey:@"key2"];
// -> { "key1" : "value", "key3" : false }

Swift

ProximitySDK.shared.sendTag("value", for: "key1");
// -> { "key1" : "value" }
ProximitySDK.shared.sendTag(1, for: "key2");
// -> { "key1" : "value", "key2" : 1 }
ProximitySDK.shared.sendTag(true, for: "key3");
// -> { "key1" : "value", "key2" : 1, "key3" : true }
ProximitySDK.shared.sendTag(false, for: "key3");
// -> { "key1" : "value", "key2" : 1, "key3" : false }
ProximitySDK.shared.sendTag(null, for: "key2");
// -> { "key1" : "value", "key3" : false }

sendTags

sendTags方法允许一次设置或取消设置多个标签。

该方法可以多次调用。当发送不同的键时，其效果是累积的。如果使用相同的键，则最后一个值会覆盖之前的值。

注意: 要使用字典发送null值，您必须使用NSNull实例传递值。

Objective-C

[JTProximitySDK.sharedInstance sendTags:@{
    @"key1" : "value",
    @"key2" : @1,
    @"key3" : @YES,
}];
// -> { "key1" : "value", "key2" : 1, "key3" : true }
[JTProximitySDK.sharedInstance sendTags:@{
    @"key2" : [NSNull null],
    @"key3" : @NO,
}];
// -> { "key1" : "value", "key3" : false }

Swift

ProximitySDK.shared.sendTags([
    "key1" : "value",
    "key2" : 1,
    "key3" : true
])
// -> { "key1" : "value", "key2" : 1, "key3" : true }
ProximitySDK.shared.sendTags([
    "key2" : NSNull(),
    "key3" : false
])
// -> { "key1" : "value", "key3" : false }

程序化禁用广告

可以通过将SDK的advertisingEnabled属性设置为false来程序化地启用/禁用广告投递。例如，为了禁用针对应用程序特定用户的广告投放，这是一个很有用的功能。在这种情况下，一旦用户登录或退出应用程序，就修改该属性。属性的默认值是true。

Objective-C

// disable advertising delivery
[JTProximitySDK.sharedInstance setAdvertisingEnabled:NO];
// enable advertising delivery
[JTProximitySDK.sharedInstance setAdvertisingEnabled:YES];

Swift

// disable advertising delivery
ProximitySDK.shared.advertisingEnabled = false
// enable advertising delivery
ProximitySDK.shared.advertisingEnabled = true

接收自定义事件

您可以通过使用ProximitySDK实例的customDelegate属性，接收自定义广告事件（如果通过后端配置），从而通过集成应用程序特定的功能来使用这些事件。

当应用程序用户与自定义操作通知交互时，将传递一个包含customAction NSString对象的参数来调用jtProximityDidReceiveCustomAction:方法。

用户同意与GDPR

作为发布者，您应该手动实现用户同意流程或使用同意管理平台（CMP），并按照IAB Europe的Mobile In-App CMP API v2.0：透明度与同意框架概述的要求请求品牌和目的同意。

启用同意流程支持

为了确保SDK在存在IAB兼容的CMP库时能够处理用户同意首选项，您必须通过ProximitySDK.setCmpEnabled:方法启用此功能，该方法默认为false。

⚠️ 注意：此方法必须在与initWithLaunchOptions:apiKey:apiSecret:方法之前调用，以确保错误免费的过程。

使用同意管理平台

当配置第三方CMP与Jointag Proximity SDK一起使用时，必须满足以下要求

为了启用广告投放，必须在CMP中配置一个custom publisher purpose，且它必须是第一个自定义目的。

实现自定义同意流程

如果您需要在不使用IAB兼容性CMP库的情况下手动处理用户同意流程，或者您使用的CMP不允许自定义“自定义出版商目的”，则可以通过实现应用内同意屏幕并使用以下方法与SDK交互来实现。

Objective-C

// Retrieve or update the manual user profiling consent
[JTProximitySDK.sharedInstance getManualConsentForType:JTPManualConsentProfiling];
[JTProximitySDK.sharedInstance setManualConsent:YES forType:JTPManualConsentProfiling];

// Retrieve or update the manual user monitoring consent
[JTProximitySDK.sharedInstance getManualConsentForType:JTPManualConsentMonitoring];
[JTProximitySDK.sharedInstance setManualConsent:YES forType:JTPManualConsentMonitoring];

// Retrieve or update the manual user advertising consent
[JTProximitySDK.sharedInstance getManualConsentForType:JTPManualConsentAdvertising];
[JTProximitySDK.sharedInstance setManualConsent:YES forType:JTPManualConsentAdvertising];

// Retrieve or update the manual user advanced tracking consent
[JTProximitySDK.sharedInstance getManualConsentForType:JTPManualConsentAdvancedTracking];
[JTProximitySDK.sharedInstance setManualConsent:YES forType:JTPManualConsentAdvancedTracking];

Swift

// Retrieve or update the manual user profiling consent
ProximitySDK.shared.getManualConsent(for: .profiling);
ProximitySDK.shared.setManualConsent(true, for: .profiling);

// Retrieve or update the manual user monitoring consent
ProximitySDK.shared.getManualConsent(for: .monitoring);
ProximitySDK.shared.setManualConsent(true, for: .monitoring);

// Retrieve or update the manual user advertising consent
ProximitySDK.shared.getManualConsent(for: .advertising);
ProximitySDK.shared.setManualConsent(true, for: .advertising);

// Retrieve or update the manual user advanced tracking consent
ProximitySDK.shared.getManualConsent(for: .advancedTracking);
ProximitySDK.shared.setManualConsent(true, for: .advancedTracking);

⚠️ 注意：当在存在CMP库的情况下使用手动同意方法时，上述方法所做的选择优先于在CMP库屏幕中用户所做的选择。

JTProximitySDK 1.16.0

JTProximitySDK 1.16.0

JTProximitySDK 1.16.0

Jointag Proximity SDK 文档

目录

安装

CocoaPods安装

手动安装

权限和服务

用户跟踪权限

通知权限

位置权限

设置

初始化SDK

iOS 13场景

处理通知

高级配置

跟踪用户标识符

广告ID和安装ID

外部用户ID

数据标签

sendTag

sendTags

程序化禁用广告

接收自定义事件

用户同意与GDPR

启用同意流程支持

使用同意管理平台

实现自定义同意流程