Meta Ads 集成

需要开发者协助

您需要开发团队的帮助来设置此集成。请与他们分享本指南。

Meta Ads 集成可让您将 Pushwoosh 受众同步到您的 Meta 广告帐户。使用它可以在广告活动中定位或排除用户，并将付费广告作为客户旅程中的另一个渠道。

使用场景

使用此集成可以：

• 在多个渠道中定位高价值用户，以增加购买或参与度
• 重新定位在其他渠道中响应较差的用户
• 建立排除受众，使忠实客户不会收到不必要的广告

先决条件

在连接 Meta Ads 之前，请确保：

• 您在 Pushwoosh 帐户中拥有 Admin 角色。有关角色和权限的工作方式，请参阅管理用户访问和权限。
• 您已设置 Facebook Business Manager 来管理您品牌的 Facebook 资产，包括广告帐户、主页和应用。
• 您有一个与您的 Business Manager 关联的有效 Facebook Ad Account。
• 您的 Facebook Business Manager 管理员已授予您计划与 Pushwoosh 一起使用的广告帐户的 Manage Campaigns 或 Manage ad accounts 权限。
• 您已接受这些帐户的广告帐户条款和条件。
• 您已接受您计划与 Pushwoosh 一起使用的 Facebook 广告帐户的 Facebook’s Custom Audiences Terms。

在 Pushwoosh 中设置 Meta Ads

1. 在 Pushwoosh 中，转到 设置 > 第三方集成。

2. 在 Meta Ads 卡片中，点击 登录页面。

3. 登录您的 Meta 帐户，然后点击 继续。

4. 选择您要连接的广告帐户。

5. 查看所请求的广告帐户和业务访问权限。

6. 点击 保存。Meta 随后会显示一条确认消息，表明您的帐户已连接。

检查连接状态

设置完成后，您将被重定向到 Pushwoosh 中的 Meta Ads 页面。

广告帐户表列出了每个连接的帐户及其：

• 广告帐户名称
• 业务帐户
• ID

打开行末的三个点，然后选择 移除广告帐户，以从 Pushwoosh 的列表中删除该广告帐户。

管理已连接的广告帐户

在 Meta Ads 页面上，点击 管理帐户 打开对话框。使用每行上的开关来包含或排除该广告帐户与此集成的关系。 点击 应用 保存更改，或点击 取消 关闭而不保存。

要调整列表视图：

• 打开或关闭 仅显示已连接 以限制显示的行。
• 在 按名称或 ID 搜索… 中输入内容以在列表中查找帐户。

将项目标签映射到 Meta 字段

映射用户属性可让您告诉 Pushwoosh 哪些 Meta 用户属性应更新您项目中的哪些 标签名称 字段。这样，当数据来自 Meta 时，它会保存在您期望的位置。

注意

对于受众同步，Pushwoosh 始终根据用户个人资料中存在的内容，从 电子邮件、电话号码 或 MADID 中为每个用户发送一个标识符。当您希望 Meta 接收除上述标识符之外的 额外 用户属性时，请配置映射。

1. 在 Meta Ads 页面上，点击 映射用户数据。

2. 对于左列中的每个 Facebook 字段，从右侧控件中选择您项目中的一个 标签名称。 仅映射您需要的行。

自动映射的字段

Pushwoosh 会自动映射这些字段。您无需在 将项目标签映射到 Meta 字段 中设置它们：

• 电子邮件
• 电话号码
• MADID

3. 点击 保存 应用映射，或点击 取消 关闭而不保存。

在 SDK 中启用 MADID 收集

Meta Ads 使用通过移动 SDK 收集的设备标识符 (MADID) 来匹配用户。 Pushwoosh SDK 不会自动收集广告标识符（Android 上的 GAID，iOS 上的 IDFA）。 两个平台都要求在读取标识符之前获得明确的用户同意。 在您的应用程序中，请求用户同意，在允许的情况下读取标识符，并将该值传递给 SDK。

Android

1. 添加依赖项

implementation 'com.google.android.gms:play-services-ads-identifier:...'

2. 声明 AD_ID 权限（targetSdk ≥ 33 时必需）

将其添加到您的 AndroidManifest.xml 中：

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

警告

如果没有此权限，在 Android 13+ 上，AdvertisingIdClient.getAdvertisingIdInfo() 会静默返回一个全零的 UUID (00000000-0000-0000-0000-000000000000)。Pushwoosh SDK 会将其规范化为 null，因此不会向服务器发送 MADID，Meta 受众匹配也将无法工作。

3. 检索 GAID 并将其传递给 SDK

getAdvertisingIdInfo 必须在后台线程上调用：

String gaid = AdvertisingIdClient.getAdvertisingIdInfo(context).getId();

Pushwoosh.getInstance().setAdvertisingId(gaid);

要清除后端存储的值，请传递 null 或空字符串：

Pushwoosh.getInstance().setAdvertisingId(null);

行为说明：

• 如果自上次成功调用以来值未发生变化，则不会发出网络请求。
• 如果网络请求失败，则在下次应用启动时重试。
• 当 Pushwoosh.stopCommunication() 处于活动状态时，该调用将被忽略。
• 零 UUID (00000000-0000-0000-0000-000000000000) 的处理方式与 null 相同——后端存储的 MADID 将被清除。

iOS

1. 将使用说明添加到 Info.plist

Apple 要求在显示 ATT 权限对话框之前提供此键：

<key>NSUserTrackingUsageDescription</key>
<string>We use your advertising identifier to show you relevant ads.</string>

2. 在您的隐私清单中声明跟踪域

如果您的应用使用 IDFA 进行跟踪，Apple 要求您在您的隐私清单 (PrivacyInfo.xcprivacy) 中列出接收跟踪数据的域。有关完整要求，请参阅 TN3182。

将 NSPrivacyTracking 设置为 true，并将 Pushwoosh 跟踪域添加到 NSPrivacyTrackingDomains：

<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.svc-nue.pushwoosh.com</string>
</array>

注意

如果用户未授予 ATT 权限，iOS 会阻止对 NSPrivacyTrackingDomains 中列出的所有域的网络请求。无论您的代码如何操作，MADID 都不会被发送。

3. 请求跟踪授权并将 IDFA 传递给 SDK

ATTrackingManager 需要 iOS 14 或更高版本。如果您的部署目标低于 iOS 14，请将调用包装在可用性检查中。

Pushwoosh SDK 不会调用 ATTrackingManager。在您的应用程序中请求跟踪授权，然后将结果传递给 SDK：

import AppTrackingTransparency
import AdSupport

if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
        let idfa = status == .authorized
            ? ASIdentifierManager.shared().advertisingIdentifier.uuidString
            : nil
        Pushwoosh.configure.setAdvertisingId(idfa)
    }
}

要清除后端存储的值，请传递 nil 或空字符串：

Pushwoosh.configure.setAdvertisingId(nil)

行为说明：

• 如果自上次成功调用以来值未发生变化，则不会发出网络请求。
• 如果网络请求失败，请在下次应用启动时再次调用 setAdvertisingId。
• 当 Pushwoosh_ALLOW_SERVER_COMMUNICATION 被禁用时，该调用将被忽略。
• 零 UUID (00000000-0000-0000-0000-000000000000) 的处理方式与 nil 或空字符串相同——后端存储的 MADID 将被清除。

从您的应用主 UI 流程中调用 requestTrackingAuthorization。Apple 建议在显示您自己的解释性屏幕之后执行此操作，而不是在启动时立即执行。

工作原理

一旦您调用 setAdvertisingId，SDK 就会将该值作为 madid 字段与应用代码和设备硬件 ID 一起发送到 Pushwoosh 跟踪端点。Pushwoosh 使用此标识符将您的设备记录与 Meta Ads 受众进行匹配以进行同步。

在旅程中同步受众

Journey Builder 中的 受众同步 点将您的旅程链接到 Meta 自定义受众。每当用户到达该点时，Pushwoosh 都会请求 Meta 将他们添加到受众或从受众中移除。

例如，您可以使用此功能停止向已注册的用户显示网络研讨会广告，这样您就不会在不再需要看到广告的人身上浪费广告支出。

要配置受众同步：

1. 打开 Journey Builder。

2. 添加一个 基于受众的入口。在 受众来源 中，选择一个定义谁进入此旅程的 Pushwoosh 细分或列表。例如，一个细分 标签 webinar_registered 设置为 true 的用户。只有这些用户会通过旅程并到达 受众同步。

3. 添加 受众同步 点。

4. 在 如何将用户信息同步到 Meta 受众 下，选择一个选项：

   • 将用户添加到受众。将每个到达此步骤的用户添加到您选择的 Meta 受众。例如，使用此选项开始向已注册但尚未参加的用户显示广告。
   • 从受众中移除用户。将每个到达此步骤的用户从该 Meta 受众中移除。在此示例中，选择此选项以停止向已注册的用户显示网络研讨会广告。

5. 在 Meta Ads 帐户 中，选择已连接的广告帐户。

6. 在 受众 中，选择 Meta 受众，例如 网络研讨会。

7. 点击 应用 保存该点，或点击 取消 关闭而不保存。

8. 完成旅程配置，然后启动它。

当这些用户到达 受众同步 时，他们将从 Meta 的 网络研讨会 受众中移除，因此他们不再在那里看到网络研讨会广告。

行为和错误处理

旅程处理取决于 Meta 帐户和受众的可用性：

• 只有当 Meta 能够从 Pushwoosh 提供的数据中匹配到用户时，Meta 才会更新受众。如果 Meta 无法匹配用户，该用户的受众不会改变，他们将继续在旅程中。
• 如果一个个人资料在连接的广告帐户断开连接时到达 受众同步 点，该个人资料的旅程将停止，Pushwoosh 会发送系统和电子邮件通知。
• 如果在 Meta 中未找到选定的受众并且 API 返回错误，该个人资料的旅程将停止，Pushwoosh 会发送系统和电子邮件通知。

受众同步统计

启动后，打开 受众同步 步骤的统计信息，以查看进入量、添加和移除以及跳过的个人资料。有关指标的详细信息，请参阅 客户旅程统计 中的 受众同步。