iOS 弹窗集成

集成 SDK

集成神策分析 SDK

在使用弹窗 SDK 之前，请确保已经集成了神策分析 iOS SDK，版本需要在 v 4.5.23及以上。详细集成步骤请参照 iOS SDK 埋点集成使用帮助文档。

集成神策弹窗 SDK

CocoaPods 方式

项目 Podfile 中添加以下配置：

pod 'SensorsFocus'

在 Podfile 目录下执行 pod install 安装 SDK。

手动集成方式

从 GitHub 获取 SDK；
将 SDK（SensorsFocus → Dynamic 中的 SensorsFocus.xcframework ）导入 App 项目，并选中 Copy items if needed。

弹窗 SDK 从 0.6.1 版本开始，支持动态库和静态库，请选择对应的 subspec 或者文件夹
弹窗 SDK 从 0.6.0 版本开始，支持诊断信息，需要依赖基础的诊断信息库，手动集成时需要引入此基础库
弹窗 SDK 从 0.7.0 版本开始，适配了神策 SDH IDM ，如果SFN 升级到了 444 及以上版本并且开通了 SDH IDM，请使用带有 IDM 的模块，例如使用 pod ‘SensorsFocus’, :subspecs=>['Dynamic+IDM']，如果没开通 SDH IDM，请勿使用带有 IDM 的模块！

初始化 SDK

首先您需要初始化神策分析 SDK，具体可参考：初始化 SDK 并开启全埋点。

神策分析 SDK 初始化完成之后，再初始化神策弹窗 SDK。参考代码如下：

#import <SensorsFocus/SensorsFocus.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

	// 1. 初始化神策分析 SDK
	...

	// 2. 初始化神策弹窗 SDK
    SFConfigOptions *sfOptions = [[SFConfigOptions alloc] initWithApiBaseURL:@"<#在线服务地址#>"];
    sfOptions.orgID = @"your org_id";   //org id
    sfOptions.accessToken = @"your access_token"; //access token
    sfOptions.campaignDelegate = self;
    [SensorsFocus startWithConfigOptions:sfOptions];

	return YES;
}

注意

对于 SF 444 及以上版本，建议升级弹窗 SDK 到 0.7.0 及以上版本，初始化时设置 orgID 和 accessToken，需要集成 SDK 带有 IDM 的相关模块
对于某些私部客户，orgID 和 accessToken 不是必选项，具体情况请联系神策技术同学来确认

设置自定义占位图

SDK 内部有预置的占位图逻辑，如果想设置自定义的占位图，可通过如下接口来设置

sfOptions.placeholderImageName = @"<#imageName#>"; // Assets 中占位图的名字

同时，对于占位图不存放在 Assets 中或者非本地的， SDK 也提供了另外一种设置方式

sfOptions.placeholderImage = <#imageData#>; // 占位图的二进制数据， NSData 类型

SDK 内部处理的占位图优先级为 placeholderImageName > placeholderImage > 内置占位图
SDK 版本号要求 >= 0.5.4

配置 Scheme

关于 Scheme 的配置方法，参考：配置 Scheme。

AppDelegate 中的 - application:openURL:options: 方法中调用 - handleOpenURL: 对神策 Scheme 进行处理。

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
	if ([[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url]) {
        return YES;
    }
	if ([SensorsFocus handleOpenURL:url]) {
		return YES;
	}
	return NO;
}

实现弹窗回调

在 SensorsFocus 初始化时，可以通过设置 SFConfigOptions campaignDelegate 来设置对弹窗的回调监听。遵守 SensorsFocusCampaignDelegate 协议，并实现以下协议方法。

设置弹窗开始触达回调

在弹窗触达开始时，SDK 会调用 - campaignDidStart: 回调方法。

/**
 弹窗开始触达回调

 @param campaign 弹窗数据
 */
- (void)campaignDidStart:(SFCampaign *)campaign {
    if (campaign.type == SFCampaignTypeCustomized) {
        // 自定义弹窗
    }
}

设置弹窗触达结束回调

在弹窗触达结束时，SDK 会调用 - campaignDidEnd: 回调方法。

/**
 弹窗触达结束回调

 @param campaign 弹窗数据
 */
- (void)campaignDidEnd:(SFCampaign *)campaign {
     
}

设置弹窗触达失败回调

在弹窗触达失败时，SDK 会调用 - campaignFailed: error: 回调方法。

/**
 弹窗触达失败回调

 @param campaign 弹窗数据
 @param error 失败错误信息。除了网络请求中系统默认的错误之外，SDK 也自定义了的部分错误，domain 为 SensorsFocusErrorDomain。错误信息如下：
    1. 图片下载失败：1000
    2. 获取测试弹窗数据请求失败：1001
*/
- (void)campaignFailed:(SFCampaign *)campaign error:(NSError *)error {
 
}

设置弹窗按钮点击回调

当用户点击预置弹窗上的按钮、图片或遮罩时，SDK 会触发 -campaignDidClick: 回调方法。

- (void)campaignDidClick:(SFCampaign *)campaign {
    switch (campaign.action.type) {
        case SensorsFocusActionTypeClose:
            //close popup
            NSLog(@"关闭弹窗");
            break;
        case SensorsFocusActionTypeCopy:
            NSLog(@"copy text: %@", campaign.action.value);
            NSLog(@"copy tip: %@", campaign.action.extra[@"copied_tip"]);
            break;
        case SensorsFocusActionTypeOpenlink:
            //open link
            NSLog(@"link text: %@", campaign.action.value);
            break;
        case SensorsFocusActionTypeCustomize:
            //customize params
            NSLog(@"customize params: %@", campaign.action.extra);
            break;
        default:
            break;
    }
}

目前支持的操作有：关闭弹窗、跳转链接、复制文本、自定义链接。对应关系如下：

序号	类型	弹窗响应	type	value	extra
1	关闭弹窗	点击后弹窗关闭	SensorsFocusActionTypeClose	nil	nil
2	跳转链接	点击后弹窗关闭	SensorsFocusActionTypeOpenlink	URL 跳转链接	nil
3	复制文本	点击后弹窗不关闭	SensorsFocusActionTypeCopy	被复制的文本	NSDictionary
4	自定义链接	点击后弹窗关闭	SensorsFocusActionTypeCustomize	nil	自定义的 key-value

注意

SDK 无法自动处理 SensorsFocusActionTypeOpenlink 和 SensorsFocusActionTypeCustomize 类型，需要手动处理页面跳转操作。

禁用弹窗在闪屏页使用

有些场景，比如闪屏页展示的时候、视频播放等，我们不想要弹窗弹出，可以实现如下接口来禁止弹窗弹出

// 实现 SensorsFocusCampaignDelegate 中的 shouldStart 方法
- (BOOL)campaignShouldStart:(SFCampaign *)campaign {
    if (闪屏页) {
        return NO;
    }
    return YES;
}

注意

此方法控制所有弹窗能否弹出，使用时对于返回 NO 的判断需要注意代码逻辑，防止逻辑错误带来所有弹窗都无法弹出

弹窗调试

创建运营计划并测试弹窗

首先在神策智能运营中创建运营计划，并且“触发条件”中的“平台类型”选择 iOS，然后配置好“触达配置”就可以点击右侧的“测试弹窗”按钮以打开二维码。

扫描二维码

使用已安装了测试 App 的设备，通过手机自带的系统相机扫描二维码，扫码后会在浏览器中打开二维码对应的网页。

唤起 App

若 App 已经成功集成 SDK 则会直接唤起 App 或提示询问是否唤起 App。

若 App 集成 SDK 存在问题或未安装 App，则会进入到如下报错界面，请检查您的 App 配置。

测试弹窗效果

跳转成功后，会在 App 内弹出弹窗。

弹窗后的关闭弹窗、点击按钮等效果与创建的运营计划一致。