MailchimpSDK 2.0.4

MailchimpSDK 2.0.4

×

维护者：Michael Patzer，Jey Starratt。

MailchimpSDK 2.0.4

Mailchimp Developer

MailchimpSDK-iOS

目录

入门
安装
初始化 SDK
收集联系信息
联系信息架构
收集联系事件
事件架构

入门

要求

  • 部署目标 iOS 12.0 或更高版本
  • Xcode 版本 11 或更高版本
  • Ruby 2.4 或更高版本（用于 fastlane）

检索 SDK 密钥

安装

选项 1: Cocoapods

要获取我们 SDK 的最新版本，请将以下内容添加到您的项目 Podfile 中

pod 'MailchimpSDK'

选项 2: 手动

  1. 克隆此存储库
  2. 运行 bundle exec fastlane create_binary_framework 以构建适用于 iOS 和 iOS 模拟器的 Swift 可执行框架。
  3. 添加 XCFramework

在项目导航器中，选择您的应用程序目标，转到“通用”选项卡，向下滚动到“框架、库和嵌入内容”。从本存储库中拖动 Mailchimp.xcframework 进入此部分。

Drag the framework into Frameworks, Libraries, and Embedded Content

选项 3: Swift 包管理器

要使用 Swift 包管理器，在 Xcode 中点击“文件”->“Swift 包”->“添加包依赖”，输入 MailchimpSDK 存储库的 URL 或您可以通过 GitHub 账户登录到 Xcode，只需键入 MailchimpSDK 以进行搜索。

初始化 SDK

initialize 方法有三个不同的字段。

  • SDK 密钥（必需）：SDK 密钥为您提供访问受众的权限。
  • 调试模式（可选）：启用调试模式以启用仅调试的功能，例如额外的日志记录。默认关闭。
  • 自动打标签（可选）：自动将联系人信息（如设备类型和平台）标记为标签。默认开启。
Mailchimp.initialize(token: sdkKey)

收集联系信息

添加联系信息

要将联系信息添加到您的Mailchimp受众中，首先实例化一个新的Contact结构。然后，将联系信息传递给createOrUpdate()方法。这将添加联系信息到您的Mailchimp受众中，并应用合并字段和/或标签。如果联系信息已存在，其信息将更新为传入的值。

var contact: Contact = Contact(emailAddress: "[email protected]")
let mergeFields = ["FNAME": MergeFieldValue.string("Example"),
                   "LNAME": MergeFieldValue.string("User")]
contact.status = .subscribed
contact.mergeFields = mergeFields
contact.tags = [Contact.Tag(name: "mobile-signup", status: .active)]
Mailchimp.createOrUpdate(contact: contact) { result in
    switch result {
    case .success:
        print("Successfully added or updated contact")
    case .failure(let error):
        print("Error: \(error.localizedDescription)")
    }
}

更新联系信息

您可以通过在添加联系信息部分中描述的相同createOrUpdate()方法来更新联系信息。

除了更新整个联系信息外，我们还提供了一些方法用于更新联系信息的单个字段。这些方法作为独立网络请求执行。要一次性更新多个字段，请使用createOrUpdate()方法。

单个字段更新方法包括

  • addTag()：给指定用户添加标签。
  • addTags()：给指定用户添加多个标签。
  • removeTag()：从指定用户中移除标签。
  • removeTags()：从指定用户中移除多个标签。
  • setMergeField()：为指定用户设置或更新合并字段。

添加/移除标签

Mailchimp.addTag(name: tagName,
                   emailAddress: "[email protected]") { result in
                   switch result {
                   case .success:
                       print("Successfully added tag: \(tagName)")
                   case .failure(let error):
                       print("Error: \(error.localizedDescription)")
                   }
               }

Mailchimp.removeTag(name: tagName,
                      emailAddress: "[email protected]") { result in
                      switch result {
                      case .success:
                         print("Successfully removed tag: \(tagName)")
                      case .failure(let error):
                         print("Error: \(error.localizedDescription)")
                      }
               }

设置合并字段

Mailchimp.setMergeField(emailAddress: "[email protected]",
                          name: fieldName,
                          value: fieldValue) { result in
                          switch result {
                          case .success:
                               print("Successfully added merge field: \(fieldName), \(fieldValue)")
                          case .failure(let error):
                               print("Error: \(error.localizedDescription)")
                          }
               }

联系架构

电子邮件

电子邮件地址是受众中每个联系人的唯一标识。每个与SDK的交互都需要电子邮件地址。

标签

用户可以在他们的联系信息中添加或删除标签。每个标签都使用一个字符串来识别。如果标签尚未在你的账户中使用，它将被创建。

自动分类

如果启用自动分类，所有创建或更新的联系都将以自动标记的形式添加iOS和Phone或Tablet。

合并字段

合并字段是可以在每个联系上设置的键值对。它们可以针对每个受众进行自定义。常见的合并字段示例包括名、姓和电话号码。可以从SDK中设置和更新合并字段的值。合并字段是基于首字母大写的字符串键实现的。键不包括两端的竖线（例如，FNAME而不是|FNAME|）。

虽然可以在受众设置中标记合并字段为必填项，但使用Mailchimp SDK时将不会强制执行这些要求。

字符串合并字段

大多数合并字段类型都表示为字符串，包括文本、数字、单选按钮、下拉菜单、日期、生日、电话号码和网站。

地址合并字段

地址类型的合并字段表示为地址结构。地址包括三个必填字段：地址行1、城市和邮编。此外还有三个可选字段：地址行2、州和国家。下面是一个地址对象的示例。

let address = Address(addressLineOne: "123 Chimp St.",
                      addressLineTwo: "Suite 456",
                      city: "Atlanta",
                      state: "GA",
                      zipCode: "30308",
                      country: CountryCode.USA)

联系状态

联系状态表示用户已同意何种类型的通信。这可以是订阅（将接收一般营销活动）或事务性（只会收到事务性电子邮件）。此值只能在创建联系时设置。如果在其他时间设置，新值将被忽略。默认情况下，如果创建时未设置此值，所有用户将被标记为事务性。

您可以通过设置 status 来订阅新联系到一般营销活动。

contact.status = .subscribed

营销许可

需要设置适当的营销许可来与添加到具有GDPR启用字段的受众的任何联系/通信。这些字段指定联系如何希望其信息被使用（例如：用于直接邮件或定制在线广告）。

通过使用对应于 marketingPermissionsId 的MarketingPermission结构并设置 enabled（如果用户授予了该许可ID的权限）来设置营销许可。

let permission1 = Contact.MarketingPermission(marketingPermissionId: "permission1", enabled: true)

收集联系事件

添加事件

要添加与联系有关的事件，首先实例化一个新的 Event 结构体。然后，将事件传入 trackEventWithAttributes() 方法。这将把事件添加到指定的联系中。

let event: Event = try! Event(emailAddress: "[email protected]", name: "signup", properties: ["source": "iOS"])
Mailchimp.trackEventWithAttributes(event: event) { result in
    switch result {
    case .success:
        print("Successfully tracked an event")
    case .failure(let error):
        print("Error: \(error.localizedDescription)")
    }
}

事件 Schema

邮箱

电子邮件地址是受众中每个联系人的唯一标识。每个与SDK的交互都需要电子邮件地址。

名字

每个事件都使用一个字符串来标识。事件名称的最大长度为 30 个字符。

属性

任何事件都可以有与之关联的属性。这些属性具有一个字符串键和字符串值。属性名称限于 A-z 和下划线。

常见问题解答

您有 Android 版本吗？

是的！您可以在这里找到它。

为什么 SDK 在我尝试创建联系时抛出错误？

请检查您是否以正确的令牌格式初始化了SDK。令牌包含 -us 后缀。

为什么调用会静默失败？

出于安全考虑，我们的SDK是只写权限的。无法通过SDK检索联系数据。调用静默失败是为了确保无法根据错误消息推断出联系数据。（例如，如果添加联系人的失败非常明显，人们可能会推断该联系人存在于您的列表中。）

如何在Objective-C项目中使用SDK？

与Objective-C项目交互的最佳方式是创建一个Swift包装对象，该对象可以初始化SDK并为您创建联系。

Mailchimp移动SDK会跟踪我的用户吗？

Mailchimp移动SDK不会跟踪您的用户。Mailchimp移动SDK会自动将您的移动应用用户添加到您的Mailchimp受众中，以便您可以向他们发送营销信息。Mailchimp不会向数据经纪人提供有关您的应用用户的信息。移动SDK不会将您的应用中的用户数据与其他应用的信息合并，以便投放定向广告。有关Mailchimp移动SDK的更多信息，请点击这里。