更新记录

1.0.0（2026-01-16）

• 首发

平台兼容性

uni-app(4.85)

uni-app x(4.85)

sn-uts-adjust

一个基于 UTS 开发的 Adjust SDK 插件，支持 Android 和 iOS 平台，提供完整的移动应用归因分析和事件跟踪功能。

UTS环境兼容性

功能特性

• ✅ SDK 初始化和配置
• ✅ 事件跟踪（支持收入、回调参数、合作伙伴参数等）
• ✅ 广告收入跟踪
• ✅ 深度链接处理
• ✅ 归因信息获取
• ✅ GDPR 支持（忘记我功能）
• ✅ 第三方分享跟踪
• ✅ 离线模式支持
• ✅ 全局回调参数和合作伙伴参数管理
• ✅ 全局事件监听（归因变化、事件跟踪、会话跟踪等）
• ✅ 设备 ID 获取（ADID、Google Ad ID、Amazon Ad ID、GAID）
• ✅ 推送令牌设置
• ✅ 外部设备 ID 设置

安装使用

1. 导入插件

插件已包含在 uni_modules 目录下，无需额外安装。

2. 在页面中使用

<script>
import { useAdjustClient } from '@/uni_modules/sn-uts-adjust'
import type {
  SnUtsAdjustInitParams,
  SnUtsAdjustEventParams,
  SnUtsAdjustAdRevenueParams,
  SnUtsAdjustGlobalData
} from '@/uni_modules/sn-uts-adjust'

export default {
  onLoad() {
    // 获取 Adjust 客户端
    const adjust = useAdjustClient()

    // 设置全局事件回调
    adjust.onGlobalCallback((data: SnUtsAdjustGlobalData) => {
      console.log('全局事件:', data.eventName, data.data)
    })

    // 初始化 SDK
    const initParams: SnUtsAdjustInitParams = {
      appToken: 'your_app_token',
      environment: 'sandbox', //  'sandbox' 或 'production'
      enableOaid: true, // Android 平台可选
      fbAppId: 'your_fb_app_id' // 可选，仅支持android
    }
    adjust.initSdk(initParams)
  }
}
</script>

平台要求

• Android: 最低 SDK 版本 22
• iOS: 最低部署目标 12.0
• HBuilderX: 3.6.8+ (uni-app) / 3.9+ (uni-app x)

API 文档

useAdjustClient()

获取 Adjust 客户端实例。

返回值: ISnUtsAdjuctClient - Adjust 客户端接口

示例:

const adjust = useAdjustClient()

onGlobalCallback(callback)

设置全局事件回调，用于监听 Adjust SDK 的各种事件。

参数:

• callback: SnUtsAdjustGlobalCallback - 全局事件回调函数

回调事件类型:

• attributionChanged - 归因信息变化
• eventTrackingSucceeded - 事件跟踪成功
• eventTrackingFailed - 事件跟踪失败
• sessionTrackingSucceeded - 会话跟踪成功
• sessionTrackingFailed - 会话跟踪失败
• launchReceivedDeeplink - 收到延迟深度链接
• initSdkFailed - SDK 初始化失败
• skanUpdated - SKAdNetwork 更新
• conversionValueUpdated - 转化值更新

示例:

adjust.onGlobalCallback((data) => {
  if (data.eventName === 'attributionChanged') {
    console.log('归因信息:', data.data)
  }
})

initSdk(params)

初始化 Adjust SDK。

参数:

• params: SnUtsAdjustInitParams - 初始化参数
  • appToken: string - Adjust App Token（必需）
  • environment: string - 环境类型，'sandbox' 或 'production'（必需）
  • enableOaid: boolean - 是否启用 OAID（Android 平台可选）
  • fbAppId: string - Facebook App ID（可选）

示例:

adjust.initSdk({
  appToken: 'your_app_token',
  environment: 'production',
  enableOaid: true,
  fbAppId: 'your_fb_app_id'
})

setEnabled(enabled)

启用或禁用 Adjust SDK。

参数:

• enabled: boolean - 是否启用

示例:

adjust.setEnabled(true)  // 启用
adjust.setEnabled(false) // 禁用

getEnabled(callback)

获取 Adjust SDK 的启用状态。

参数:

• callback: SnUtsAdjustCallback - 回调函数，返回 { code: number, data: UTSJSONObject }

示例:

adjust.getEnabled((result) => {
  if (result.code === 0) {
    console.log('SDK 已启用')
  }
})

trackEvent(params)

跟踪自定义事件。

参数:

• params: SnUtsAdjustEventParams - 事件参数
  • eventToken: string - 事件 Token（必需）
  • callbackId: string - 回调 ID（可选）
  • orderId: string - 订单 ID（可选）
  • productId: string - 产品 ID（可选）
  • purchaseToken: string - 购买 Token（可选）
  • deduplicationId: string - 去重 ID（可选）
  • revenue: UTSJSONObject - 收入信息，格式：{ revenue: number, currency: string }（可选）
  • callbackParams: UTSJSONObject - 回调参数（可选）
  • partnerParams: UTSJSONObject - 合作伙伴参数（可选）

示例:

// 基础事件跟踪
adjust.trackEvent({
  eventToken: 'abc123'
})

// 带收入的事件跟踪
adjust.trackEvent({
  eventToken: 'abc123',
  revenue: {
    revenue: 9.99,
    currency: 'USD'
  },
  callbackParams: {
    key1: 'value1',
    key2: 'value2'
  }
})

trackAdRevenue(source, params)

跟踪广告收入。

参数:

• source: string - 广告来源（如 'admob', 'facebook', 'applovin' 等）
• params: SnUtsAdjustAdRevenueParams - 广告收入参数
  • adImpressionsCount: number - 广告展示次数（可选）
  • adRevenueNetwork: string - 广告收入网络（可选）
  • adRevenueUnit: string - 广告收入单元（可选）
  • adRevenuePlacement: string - 广告收入位置（可选）
  • revenue: UTSJSONObject - 收入信息，格式：{ revenue: number, currency: string }（可选）
  • callbackParams: UTSJSONObject - 回调参数（可选）
  • partnerParams: UTSJSONObject - 合作伙伴参数（可选）

示例:

adjust.trackAdRevenue('admob', {
  adImpressionsCount: 100,
  adRevenueNetwork: 'AdMob',
  revenue: {
    revenue: 10.5,
    currency: 'USD'
  }
})

getAttribution(callback)

获取当前归因信息。

参数:

• callback: SnUtsAdjustCallback - 回调函数

返回数据结构:

{
  code: number,  // 0 表示成功，-1 表示失败
  data: {
    trackerToken?: string,
    trackerName?: string,
    network?: string,
    campaign?: string,
    adgroup?: string,
    creative?: string,
    clickLabel?: string,
    costType?: string,
    costAmount?: number,
    costCurrency?: string,
    fbInstallReferrer?: string
  }
}

示例:

adjust.getAttribution((result) => {
  if (result.code === 0) {
    console.log('归因信息:', result.data)
  }
})

getAdid(callback)

获取 Adjust Device ID (ADID)。

参数:

• callback: SnUtsAdjustStringCallback - 回调函数，返回 ADID 字符串

示例:

adjust.getAdid((adid) => {
  console.log('ADID:', adid)
})

getSdkVersion(callback)

获取 Adjust SDK 版本号。

参数:

• callback: SnUtsAdjustStringCallback - 回调函数，返回版本号字符串

示例:

adjust.getSdkVersion((version) => {
  console.log('SDK 版本:', version)
})

setPushToken(token)

设置推送令牌。

参数:

• token: string - 推送令牌

示例:

adjust.setPushToken('your_push_token')

setOfflineMode(enabled)

设置离线模式。在离线模式下，事件会被缓存，待网络恢复后发送。

参数:

• enabled: boolean - 是否启用离线模式

示例:

adjust.setOfflineMode(true)  // 启用离线模式
adjust.setOfflineMode(false) // 切换回在线模式

getLastDeeplink(callback)

获取最后一个深度链接。

参数:

• callback: SnUtsAdjustStringCallback - 回调函数，返回深度链接 URL

示例:

adjust.getLastDeeplink((deeplink) => {
  console.log('深度链接:', deeplink)
})

processDeeplink()

处理深度链接。在 Android 平台，需要在 Activity 的 onNewIntent 中调用。

示例:

adjust.processDeeplink()

gdprForgetMe()

执行 GDPR "忘记我"操作，删除用户的所有数据。

示例:

adjust.gdprForgetMe()

trackThirdPartySharing(params)

跟踪第三方分享。

参数:

• params: UTSJSONObject - 第三方分享参数
  • isEnabled: boolean - 是否启用第三方分享
  • granularOptions: Array<Array<string>> - 细粒度选项，格式：[['partner', 'key', 'value'], ...]
  • partnerSharingSettings: Array<Array<any>> - 合作伙伴分享设置，格式：[['partner', 'key', boolean], ...]

示例:

adjust.trackThirdPartySharing({
  isEnabled: true,
  granularOptions: [
    ['partner1', 'key1', 'value1']
  ],
  partnerSharingSettings: [
    ['partner1', 'key1', true]
  ]
})

setExternalDeviceIdInDelay(deviceId)

设置外部设备 ID（延迟设置）。

参数:

• deviceId: string - 外部设备 ID

示例:

adjust.setExternalDeviceIdInDelay('external_device_id')

addGlobalCallbackParameter(key, value)

添加全局回调参数。

参数:

• key: string - 参数键
• value: string - 参数值

示例:

adjust.addGlobalCallbackParameter('key1', 'value1')

addGlobalPartnerParameter(key, value)

添加全局合作伙伴参数。

参数:

• key: string - 参数键
• value: string - 参数值

示例:

adjust.addGlobalPartnerParameter('key1', 'value1')

removeGlobalCallbackParameter(key)

移除指定的全局回调参数。

参数:

• key: string - 参数键

示例:

adjust.removeGlobalCallbackParameter('key1')

removeGlobalPartnerParameter(key)

移除指定的全局合作伙伴参数。

参数:

• key: string - 参数键

示例:

adjust.removeGlobalPartnerParameter('key1')

removeGlobalCallbackParameters()

移除所有全局回调参数。

示例:

adjust.removeGlobalCallbackParameters()

removeGlobalPartnerParameters()

移除所有全局合作伙伴参数。

示例:

adjust.removeGlobalPartnerParameters()

getGoogleAdId(callback)

获取 Google Ad ID（仅 Android 平台支持，iOS 返回空字符串）。

参数:

• callback: SnUtsAdjustStringCallback - 回调函数

示例:

adjust.getGoogleAdId((gaid) => {
  console.log('Google Ad ID:', gaid)
})

getAmazonAdId(callback)

获取 Amazon Ad ID（仅 Android 平台支持，iOS 返回空字符串）。

参数:

• callback: SnUtsAdjustStringCallback - 回调函数

示例:

adjust.getAmazonAdId((amazonAdId) => {
  console.log('Amazon Ad ID:', amazonAdId)
})

getGaid(callback)

获取 Google Advertising ID（仅 Android 平台支持，iOS 返回空字符串）。

参数:

• callback: SnUtsAdjustStringCallback - 回调函数

示例:

adjust.getGaid((gaid) => {
  console.log('GAID:', gaid)
})

使用示例

基础示例

<template>
  <view class="container">
    <button @click="initAdjust">初始化 Adjust</button>
    <button @click="trackSimpleEvent">跟踪简单事件</button>
    <button @click="trackRevenueEvent">跟踪收入事件</button>
    <button @click="getAttribution">获取归因信息</button>
  </view>
</template>

<script>
import { useAdjustClient } from '@/uni_modules/sn-uts-adjust'
import type {
  SnUtsAdjustInitParams,
  SnUtsAdjustEventParams,
  SnUtsAdjustGlobalData
} from '@/uni_modules/sn-uts-adjust'

export default {
  data() {
    return {
      adjust: null as any
    }
  },
  onLoad() {
    this.adjust = useAdjustClient()

    // 设置全局事件回调
    this.adjust.onGlobalCallback((data: SnUtsAdjustGlobalData) => {
      console.log('Adjust 事件:', data.eventName, data.data)

      if (data.eventName === 'attributionChanged') {
        console.log('归因信息已更新:', data.data)
      }
    })
  },
  methods: {
    initAdjust() {
      const params: SnUtsAdjustInitParams = {
        appToken: 'your_app_token',
        environment: 'sandbox' // 开发环境使用 'sandbox'，生产环境使用 'production'
      }
      this.adjust.initSdk(params)
    },

    trackSimpleEvent() {
      const params: SnUtsAdjustEventParams = {
        eventToken: 'abc123'
      }
      this.adjust.trackEvent(params)
    },

    trackRevenueEvent() {
      const params: SnUtsAdjustEventParams = {
        eventToken: 'xyz789',
        revenue: {
          revenue: 9.99,
          currency: 'USD'
        },
        callbackParams: {
          product_id: 'product_123',
          product_name: 'Premium Subscription'
        }
      }
      this.adjust.trackEvent(params)
    },

    getAttribution() {
      this.adjust.getAttribution((result) => {
        if (result.code === 0) {
          console.log('归因信息:', result.data)
          uni.showToast({
            title: '获取成功',
            icon: 'success'
          })
        } else {
          uni.showToast({
            title: '获取失败',
            icon: 'error'
          })
        }
      })
    }
  }
}
</script>

动态修改属性

<script>
export default {
  methods: {
    toggleSDK() {
      this.adjust.getEnabled((result) => {
        const isEnabled = result.code === 0
        this.adjust.setEnabled(!isEnabled)
        console.log(`SDK 已${!isEnabled ? '启用' : '禁用'}`)
      })
    },

    switchToOfflineMode() {
      this.adjust.setOfflineMode(true)
      console.log('已切换到离线模式')
    },

    switchToOnlineMode() {
      this.adjust.setOfflineMode(false)
      console.log('已切换回在线模式')
    }
  }
}
</script>

高级用法

<script>
export default {
  methods: {
    // 跟踪广告收入
    trackAdRevenue() {
      this.adjust.trackAdRevenue('admob', {
        adImpressionsCount: 100,
        adRevenueNetwork: 'AdMob',
        revenue: {
          revenue: 10.5,
          currency: 'USD'
        },
        callbackParams: {
          ad_unit_id: 'ca-app-pub-xxx',
          ad_format: 'banner'
        }
      })
    },

    // 添加全局参数
    addGlobalParams() {
      this.adjust.addGlobalCallbackParameter('user_id', '12345')
      this.adjust.addGlobalCallbackParameter('user_type', 'premium')
      this.adjust.addGlobalPartnerParameter('campaign_id', 'summer_2024')
    },

    // 跟踪第三方分享
    trackThirdPartySharing() {
      this.adjust.trackThirdPartySharing({
        isEnabled: true,
        granularOptions: [
          ['facebook', 'key1', 'value1'],
          ['google', 'key2', 'value2']
        ],
        partnerSharingSettings: [
          ['facebook', 'enable', true],
          ['google', 'enable', false]
        ]
      })
    },

    // 处理深度链接
    handleDeeplink() {
      // Android 平台需要在 Activity 的 onNewIntent 中调用
      this.adjust.processDeeplink()

      // 获取最后一个深度链接
      this.adjust.getLastDeeplink((deeplink) => {
        if (deeplink) {
          console.log('深度链接:', deeplink)
          // 处理深度链接逻辑
        }
      })
    },

    // GDPR 忘记我
    handleGDPRForgetMe() {
      uni.showModal({
        title: '确认',
        content: '确定要删除所有数据吗？此操作不可撤销。',
        success: (res) => {
          if (res.confirm) {
            this.adjust.gdprForgetMe()
            uni.showToast({
              title: '数据已删除',
              icon: 'success'
            })
          }
        }
      })
    }
  }
}
</script>

注意事项

1. 平台差异

• Android 平台:

  • 支持 OAID（需要设置 enableOaid: true）
  • 支持 Google Ad ID、Amazon Ad ID、GAID 获取
  • 深度链接处理需要在 Activity 的 onNewIntent 中调用 processDeeplink()

• iOS 平台:

  • 不支持 OAID、Google Ad ID、Amazon Ad ID、GAID（相关方法返回空字符串）
  • 深度链接通过 AppDelegate 的 openURL 方法自动处理

2. 使用限制

• SDK 初始化必须在应用启动时尽早调用，建议在 onLoad 或 onLaunch 中初始化
• 事件 Token 需要在 Adjust 后台配置
• 生产环境必须使用 environment: 'production'，开发测试使用 environment: 'sandbox'
• 全局参数会在所有后续的事件和会话中自动包含
• 离线模式下的事件会在网络恢复后自动发送

3. 性能优化

• 事件跟踪是异步的，不会阻塞主线程
• 建议在应用启动时设置全局事件回调，避免重复设置
• 使用离线模式可以在网络不佳时缓存事件，提高用户体验
• 全局参数应谨慎使用，避免添加过多参数影响性能

4. 常见问题

Q: SDK 初始化失败怎么办？

A: 检查以下几点：

1. 确认 appToken 是否正确
2. 确认 environment 参数是否正确（'sandbox' 或 'production'）
3. 查看全局事件回调中的 initSdkFailed 事件，获取详细错误信息

Q: 事件跟踪没有生效？

A: 检查以下几点：

1. 确认 SDK 已正确初始化
2. 确认事件 Token 在 Adjust 后台已配置
3. 确认环境设置正确（sandbox 环境的事件不会出现在生产环境的数据中）
4. 查看全局事件回调中的 eventTrackingFailed 事件，获取详细错误信息

Q: 如何获取归因信息？

A: 有两种方式：

1. 通过 getAttribution() 方法主动获取
2. 通过全局事件回调监听 attributionChanged 事件

Q: 深度链接如何处理？

A:

• Android 平台：在 Activity 的 onNewIntent 方法中调用 processDeeplink()
• iOS 平台：深度链接会自动处理，也可以通过 getLastDeeplink() 获取最后一个深度链接

Q: 如何测试事件跟踪？

A:

1. 使用 environment: 'sandbox' 进行测试
2. 在 Adjust 后台的测试控制台中查看事件
3. 通过全局事件回调监听事件跟踪结果