Freshpaint 反应原生 SDK

综合分析跟踪SDK,用于具有高级属性、自动跟踪和隐私特性的回放原生应用程序.

联合国 Freshpaint 反应原生 SDK 参考

目录

• 安装
• 快速启动
• 核心特征
  • 事件跟踪
  • 用户标识
  • 组
  • 自定义属性
• MMP 归属
  • App 第一个打开
  • 深链接跟踪
  • ATT(App跟踪透明度)
  • SKad网络
  • 平台特定归属
• 自动跟踪
• 高级配置
• API 参考

安装

npm install @freshpaint/freshpaint-react-native
# or
yarn add @freshpaint/freshpaint-react-native

iOS 设置

cd ios && pod install

添加到您的 Info.plist 如果请求ATT:

<key>NSUserTrackingUsageDescription</key>
<string>This app would like to track your activity for personalized ads and analytics.</string>

Android 设置

不需要额外设置。 SDK自动链接本地模块.

快速启动

import Freshpaint from '@freshpaint/freshpaint-react-native';

// Initialize the SDK
Freshpaint.init('YOUR_API_KEY', {
  autoRequestATT: true, // Automatically request ATT on iOS (optional)
});

// Track an event
Freshpaint.track('Product Viewed', {
  product_id: '123',
  product_name: 'Premium Widget',
  price: 29.99,
});

// Identify a user
Freshpaint.identify('user_123', {
  email: '[email protected]',
  plan: 'premium',
});

核心特征

事件跟踪

跟踪带有可选属性的自定义事件 :

Freshpaint.track('Button Clicked', {
  button_name: 'Sign Up',
  screen: 'Home',
});

整合选项

向特定目的地发送事件 :

Freshpaint.track(
  'Purchase Completed',
  {
    total: 99.99,
    items: 3,
  },
  {
    integrations: {
      'Google Analytics': true,
      Mixpanel: false,
    },
  },
);

用户标识

与特定用户的相关活动:

// Identify with user ID and properties
Freshpaint.identify('user_123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium',
});

// Update user properties without changing ID
Freshpaint.identify({
  last_login: new Date().toISOString(),
});

识别的整合选项

Freshpaint.identify(
  'user_123',
  {
    email: '[email protected]',
  },
  {
    integrations: {
      Salesforce: true,
      Intercom: true,
    },
  },
);

组

团体(团队、公司等)的联系用户:

// Set group with properties
Freshpaint.group('company_456', {
  name: 'Acme Corp',
  plan: 'enterprise',
  employees: 500,
});

// Update group properties without changing ID
Freshpaint.group({
  subscription_status: 'active',
});

组的整合选项

Freshpaint.group(
  'company_456',
  {
    name: 'Acme Corp',
  },
  {
    integrations: {
      Salesforce: true,
    },
  },
);

自定义属性

在所有事件上添加自定义属性 :

// Add properties (merged with existing)
Freshpaint.addEventProperties({
  app_version: '2.1.0',
  environment: 'production',
});

// Add properties with lower priority (won't override existing)
Freshpaint.addInitialEventProperties({
  default_currency: 'USD',
});

// Remove a property
Freshpaint.removeEventProperty('environment');

重置用户状态

清除所有用户数据( 登录时有用) :

Freshpaint.reset();

这说明:

• 用户名
• 用户属性
• 组标识与属性
• 自定义事件属性
• 生成新设备 ID

MMP 归属

SDK提供全面的移动测量伙伴(MMP)属性能力,自动收集数据并进行事件跟踪.

App 第一个打开

自动发射 Application Installed 包含完整属性数据的首次应用启动事件.

收集到的东西:

常见( iOS & Android) :

• install_timestamp - ISO 8601第一次打开的印章
• device_id - 新鲜油漆设备标识符
• persistent_device_id - 幸存的应用软件未安装/再安装
• os_version - OS 版本字符串
• version - 捆绑的App版本
• build - 应用程序建筑编号
• user_agent - 用户代理字符串
• UTM 参数utm_source, (中文(简体) ), utm_medium, (中文(简体) ), utm_campaign, (中文(简体) ), utm_term, (中文(简体) ), utm_content(中文(简体) )
• 35个广告点击ID(见 深链接跟踪 完整清单)

iOS: (英语)

• idfv - 供应商标识符(随时可用)
• advertisingId - 广告标识员/以色列国防军(仅在ATT授权的情况下)
• att_status - ATT授权地位authorized, (中文(简体) ), denied, (中文(简体) ), restricted, (中文(简体) ), notDetermined(中文(简体) )
• skan_registration_attempted - 布尔表示SKadNetwork注册
• apple_ads_token - Apple Search Ads归属符 (iOS 14.3+,如果有的话)

机器人:

• advertisingId - Google 广告ID(GAID) - 首选标识符
• android_id - Android ID(GAID不可用时返回)
• limit_ad_tracking - 布尔表示广告跟踪偏好
• install_referrer - 游戏存储器安装裁判员字符串
• referrer_click_timestamp - 点击广告的Unix时间戳
• install_begin_timestamp - 安装启动的无九时间戳

谷歌政策合规 : SDK遵循了Google Play政策,从未同时发送GAID和 android_id 同一请求。 它更喜欢GAID,然后掉回 android_id 只有在GAID不可用时.

示例有效载荷 :

{
  event: 'Application Installed',
  properties: {
    custom_props: {
      install_timestamp: '2024-01-15T10:30:00.000Z',
      device_id: 'abc123...',
      persistent_device_id: 'xyz789...',
      os_version: '17.2',
      version: '1.0.0',
      build: '123',
      user_agent: 'MyApp/1.0.0 (iPhone; iOS 17.2)',

      // iOS-specific
      idfv: '12345678-1234-1234-1234-123456789012',
      advertisingId: '87654321-4321-4321-4321-210987654321', // if authorized
      att_status: 'authorized',
      skan_registration_attempted: true,

      // Attribution params (if opened via deep link)
      utm_source: 'facebook',
      utm_campaign: 'summer_sale',
      fbclid: 'abc123',
      gclid: 'xyz456',
    }
  }
}

深链接跟踪

自动跟踪深链接随完全归属解析而打开.

活动 :

• 冷启动( 应用不运行 ) : 火灾 deeplink 有 URL 和参数的事件
• 热开( 应用背景): 有火 deeplink 前景事件

支持的归属参数:

UTM参数(5):

• utm_source, (中文(简体) ), utm_medium, (中文(简体) ), utm_campaign, (中文(简体) ), utm_term, (中文(简体) ), utm_content

阿德网络点击ID(35):

开发 URL 过滤 :

SDK 自动过滤出开发 URL 以防止错误的归属 :

• localhost, (中文(简体) ), 127.0.0.1
• 私人 IP 范围 : 192.168.*.*, (中文(简体) ), 10.*.*.*, (中文(简体) ), 172.16-31.*.*
• Expo 开发客户端 URL
• 反应本地调试器 URL

示例深链接事件 :

{
  event: 'Deep Link Opened',
  properties: {
    custom_props: {
      url: 'myapp://product/123?utm_source=facebook&fbclid=abc123',
      utm_source: 'facebook',
      fbclid: 'abc123',

      // All current device info is included
      idfv: '...',
      advertisingId: '...',
      att_status: 'authorized',
      app_version: '1.0.0',
      user_agent: '...',
    }
  }
}

ATT(App跟踪透明度)

控制并监控iOS App跟踪透明许可.

自动请求ATT

SDK初始化时自动请求ATT :

Freshpaint.init('YOUR_API_KEY', {
  autoRequestATT: true, // Show ATT prompt before first open event
});

何时流动 autoRequestATT: true数字 :

1. SDK 初始化
2. 请求获得ATT许可
3. 用户响应( 或先前已响应)
4. Application Installed 当前ATT状态的事件火灾

时间戳何时能被抓住?

SDK可以捕捉ATT批准的时间戳 仅限 新请求的时间 autoRequestATT: true。 。 。 .

无法捕获时间戳 :

• 用户在 SDK 安装前已经获得许可
• 主机应用请求 ATT (当 autoRequestATT: false(中文(简体) )
• 在上一个应用版本中获得了许可

手动控制

在程序上请求ATT许可:

// Check current status (doesn't show prompt)
const status = await Freshpaint.getTrackingAuthorizationStatus();
// Returns: 'authorized' | 'denied' | 'restricted' | 'notDetermined'

// Request permission (shows prompt if notDetermined)
const status = await Freshpaint.requestTrackingAuthorization();
// Returns same status values, safe to call multiple times

获得广告标识符

// Returns Advertising ID (IDFA on iOS, GAID on Android) if authorized/available, null otherwise
const advertisingId = await Freshpaint.getAdvertisingIdentifier();

// Get IDFV (iOS only, always available)
const idfv = await Freshpaint.getIdentifierForVendor();

SKad网络

iOS 11.3+ 隐私保护属性归属框架.

自动注册

SDK在第一次应用启动时(称为在 Application Installed) (中文(简体) ).

版本支持 :

• iOS 16.1+: 用途 updatePostbackConversionValue 粗切转换值
• iOS 15.4-16.0: 用途 updatePostbackConversionValue (只有罚款)
• iOS 11.3-15.3: 使用遗产 registerAppForAdNetworkAttribution (折旧)

自定义转换值

更新转换值以向广告网络显示安装后的事件 :

// Simple update (iOS 15.4+)
await Freshpaint.updateSKANConversionValue(42);

// Full update with coarse value and lock (iOS 16.1+)
await Freshpaint.updateSKANConversionValue(
  42, // value: 0-63
  'high', // coarseValue: 'low' | 'medium' | 'high'
  true, // lockWindow: prevent further updates
);

参数:

• value (0-63):细纹转换值
• coarseValue: iOS 16.1+ 仅被旧版本忽略
• lockWindow: iOS 16.1+ 仅被旧版本忽略

回返情况: true 如果尝试更新, false 如果不支持的话

平台特定归属

iOS 归属数据

const data = await Freshpaint.getAttributionData();

// Returns:
{
  idfv: '...',                 // Always available
  advertisingId: '...',        // Only if ATT authorized (IDFA)
  att_status: 'authorized',    // ATT status
  version: '1.0.0',
  build: '123',
  user_agent: '...',
  persistent_device_id: '...', // Survives uninstall (Keychain)
  device_id: '...',            // Freshpaint device ID
  is_first_launch: false,      // True only on first app launch

  // Attribution params from deep link (if any)
  utm_source: 'facebook',
  fbclid: '...',
}

Android 分配数据

const data = await Freshpaint.getAttributionData();

// Returns (with GAID available):
{
  advertisingId: '...',           // Google Advertising ID (GAID) - preferred
  // android_id NOT included when GAID is available (Google policy)
  limit_ad_tracking: false,
  version: '1.0.0',
  build: '123',
  user_agent: '...',
  persistent_device_id: '...',    // Same as advertisingId when GAID available
  device_id: '...',               // Freshpaint device ID
  is_first_launch: false,

  // Play Install Referrer (if available)
  install_referrer: 'utm_source=google&utm_medium=cpc',
  referrer_click_timestamp: 1234567890,
  install_begin_timestamp: 1234567891,

  // Attribution params from deep link (if any)
  utm_source: 'google',
  gclid: '...',
}

// Returns (when GAID unavailable - fallback):
{
  // advertisingId NOT included when unavailable
  android_id: '...',              // Android ID used as fallback
  limit_ad_tracking: false,
  version: '1.0.0',
  build: '123',
  user_agent: '...',
  persistent_device_id: '...',    // Same as android_id when GAID unavailable
  device_id: '...',               // Freshpaint device ID
  is_first_launch: false,
  // ... other fields
}

播放安装参考器( 只有 Android)

单独获取 Play Store 安装裁判员数据 :

const referrer = await Freshpaint.getPlayInstallReferrer();

// Returns:
{
  install_referrer: 'utm_source=google&utm_medium=cpc',
  referrer_click_timestamp: 1234567890, // seconds since epoch
  install_begin_timestamp: 1234567891,
}

特征 :

• 第一次接取后缓存( 随后的快速呼叫)
• 如果 Play Store 服务不响应, 则暂停5秒
• 返回空对象, 如果无法使用, 或在 iOS 上

自动跟踪

SDK为通用的UI交互提供了全面的自动跟踪能力. 所有自动抓取的事件前缀为 $ (除外) screen_view) (中文(简体) ).

反应导航

自动跟踪屏幕视图 :

import { NavigationContainer } from '@react-navigation/native';
import Freshpaint from '@freshpaint/freshpaint-react-native';

const navigationRef = React.createRef();

<NavigationContainer
  ref={navigationRef}
  onReady={() => {
    Freshpaint.withReactNavigationAutotrack(navigationRef);
  }}
>
  {/* Your navigation stack */}
</NavigationContainer>;

火灾 screen_view 有屏幕名称和路由参数的事件.

可触摸性和可按性

盘旋用于跟踪压力的组件 :

import { TouchableOpacity, Pressable } from 'react-native';
import Freshpaint from '@freshpaint/freshpaint-react-native';

// Higher-Order Components
const FreshpaintTouchable = Freshpaint.withFreshpaintTouchableAutocapture(TouchableOpacity);
const FreshpaintPressable = Freshpaint.withFreshpaintPressableAutocapture(Pressable);

// Usage
<FreshpaintTouchable onPress={handlePress}>
  <Text>Track This Press</Text>
</FreshpaintTouchable>;

火灾 $element_clicked 包含组件元数据的事件.

文本输入

音轨文本输入更改 :

const FreshpaintTextInput = Freshpaint.withFreshpaintTextInputAutocapture(TextInput);

<FreshpaintTextInput placeholder="Email" onChangeText={handleChange} />;

火灾 $text_input_changed 事件.

开关

音轨切换切换 :

<Switch
  value={enabled}
  onValueChange={(value) => {
    Freshpaint.autotrackSwitchChange(value, { switch_id: 'notifications' });
    setEnabled(value);
  }}
/>

滚动视图

音轨滚动 :

<ScrollView
  onScroll={(event) => {
    Freshpaint.autocaptureScrollView(event.nativeEvent);
  }}
  scrollEventThrottle={400}
>
  {/* Content */}
</ScrollView>

忽略元素

防止跟踪特定要素:

import { FreshpaintIgnore } from '@freshpaint/freshpaint-react-native';

<FreshpaintIgnore>
  <SensitiveComponent />
</FreshpaintIgnore>;

高级配置

初始化选项

Freshpaint.init('YOUR_API_KEY', {
  autoRequestATT: true, // Request ATT on iOS (default: false)
  apiEndpoint: 'custom-endpoint', // Custom API endpoint
  batchEvents: true, // Batch events (default: false)
  eventUploadPeriodMillis: 30000, // Upload interval (default: 30s)
  // ... see full documentation for all options
});

选择退出

禁用对隐私意识用户的跟踪 :

// Opt out of tracking
Freshpaint.setOptOut(true);

// Re-enable tracking
Freshpaint.setOptOut(false);

API 参考

初始化

事件跟踪

用户管理

自定义属性

归属

ATT (iOS) (美国)

SKadNetwork (iOS) (英语)

隐私

平台支持

• iOS: (英语) 13.0+ (韩语)
• 机器人: API 21+ (Android 5.0+) (英语)
• 原生反应 : 0.70.0+ (单位:千美元)

许可证

麻省理工学院

支助

• 联合国 https://documentation.freshpaint.io 互联网档案馆的存檔,存档日期2013-12-22
• 问题: https://github.com/refreshpaint-io/refreshpaint-resact-native/issues 互联网档案馆的存檔,存档日期2013-12-22
• 电子邮件 : 支持@ freshpaint.io