ometria.react_native_sdk
v2.4.1
Ometria 通过发送个性化电子邮件和推送通知，帮助您的营销部门了解客户并更好地与客户互动。
该应用程序有两个主要目标：
对于您的移动应用程序，这意味着：
与此 SDK 集成的应用程序开发人员应遵循以下指南。您还可以查看我们提供的示例应用程序作为参考实现。
请参阅 Ometria 帮助中心的使用 Firebase 凭据设置您的移动应用，并按照其中的步骤获取 API 密钥。
将 Ometria 引入 ReactNative 项目的最简单方法是使用npm install或yarn add 。
npm install react-native-ometria或yarn add react-native-ometria react-native-ometria安装Ometria ReactNative包注意：如果您在安装库时遇到问题，请考虑从打字稿配置中排除该示例，例如：
{
...,
"exclude": ["example"]
}
对于iOS您需要安装 Pods pod install来创建本地 CocoaPods 规范镜像。
如果您在运行 pod install 时遇到The Swift pod 'Ometria' depends upon 'FirebaseMessaging'错误，请考虑添加use_frameworks! :linkage => :static 。
要初始化 Ometria SDK，您需要输入2. 开始之前的 API 密钥。
import Ometria from 'react-native-ometria' ;
await Ometria . initializeWithApiToken ( 'API_KEY' , {
notificationChannelName : 'Example Channel Name' , // optional, only for Android
appGroupIdentifier : 'group.com.ometria.sampleRN' , // optional, only for iOS
} ) ;从版本 2.3.0 开始，SDK 允许重新初始化 Ometria 实例。因此，如果需要，您可以稍后在应用程序中再次调用此方法。
您可以在第二个可选选项参数中指定 Android 通知通道的自定义名称。默认通道名称为<blank> 。
您还可以在第二个可选选项参数中指定应用程序组标识符。对于 iOS，请参阅本部分。
默认情况下，Ometria 会记录运行时遇到的任何错误，这些日志可在开发环境的控制台中访问。
如果您想了解有关后台发生的情况的更多信息，您可以启用高级日志记录。只需在初始化库后添加以下行：
Ometria . isLoggingEnabled ( true ) ;您需要了解用户在平台上的行为才能了解他们。某些行为可以自动检测到，其他事件则需要应用程序开发人员进行跟踪。
其中许多方法在我们的网站跟踪器中都有类似的事件。
例如，客户识别事件需要客户 ID 或电子邮件 - 这些标识符必须与数据 API 中的相同。如果您同时指定电子邮件和客户 ID，则两者需要匹配。
Ometria 方面会将这些事件合并为客户行为的一个大型跨渠道视图。如果您使用不一致的电子邮件/客户 ID，可能会导致创建重复的配置文件或数据丢失。
SDK初始化后，您可以通过调用其专用方法来跟踪事件。
应用程序用户刚刚进行了身份验证，即登录。
Ometria . trackProfileIdentifiedByCustomerIdEvent ( 'test_customer_id' ) ;他们的客户 ID是他们在数据库中的用户 ID 。
有时，用户仅提供其电子邮件地址，而没有完全登录或拥有帐户。在这种情况下，Ometria 可以根据电子邮件进行配置匹配：
Ometria . trackProfileIdentifiedByEmailEvent ( '[email protected]' ) ;拥有customerId可以使配置文件匹配更加稳健。
它与发送电子邮件事件并不相互排斥；为了获得最佳集成，您应该在获得信息后立即发送任一事件。这两个事件对于 SDK 的功能至关重要，因此请确保尽早发送它们。在此重申，这些标识符必须与您在电子商务平台中使用并发送到 Ometria（通过数据 API 或其他方式）的标识符相同。如果您同时指定电子邮件和客户 ID，则两者需要匹配。我们在集成中看到的一个典型错误是应用程序在每次登录时生成一个新的客户 ID（与 Ometria 中存储的客户 ID 不匹配）。为了避免这种情况，请在服务器上集中生成这些 ID，并通过 Ometria 移动 SDK 和 Ometria 数据 API 发送一致的 ID。如果生成一致的 ID 不切实际，我们建议仅使用电子邮件来识别联系人。
撤消 profileIdentified 事件。如果用户注销，您可以使用它。
Ometria . trackProfileDeidentifiedEvent ( ) ;目前，此事件会从手机的本地存储中清除存储的 ID（电子邮件和/或客户 ID）。它在 Ometria 中没有其他作用。
访问者点击/点击/查看/突出显示或以其他方式表现出对产品的兴趣。
例如，访问者搜索一个术语并从一组结果中选择一个产品预览，或者浏览一类衣服，然后单击特定的衬衫以查看更大的图片。
此活动旨在吸引访客对该产品的兴趣。
Ometria . trackProductViewedEvent ( 'product_id' ) ;访问者查看了包含购物篮内容的专用页面、屏幕或模式：
Ometria . trackBasketViewedEvent ( ) ;访客更改了他们的购物篮：
const items : OmetriaBasketItem [ ] = [
{
productId : 'product-1' ,
sku : 'sku-product-1' ,
quantity : 1 ,
price : 12.0 ,
variantId : 'variant-1' ,
} ,
{
productId : 'product-2' ,
sku : 'sku-product-2' ,
quantity : 2 ,
price : 9.0 ,
variantId : 'variant-2' ,
} ,
{
productId : 'product-3' ,
sku : 'sku-product-3' ,
quantity : 3 ,
price : 20.0 ,
variantId : 'variant-3' ,
} ,
] ;
Ometria . trackBasketUpdatedEvent ( {
totalPrice : 12.0 ,
id : 'basket_id_eg' ,
currency : 'USD' ,
items ,
link : 'link_eg' ,
} ) ;此事件将当前的全部购物篮作为参数 - 而不仅仅是更新的部分。
这有助于从丢失或不同步的购物篮事件中恢复：最新更新始终是权威的。
OmetriaBasketItem是一个描述购物篮项目内容的对象。它可以根据不同的规则和正在应用的促销活动有自己的价格和数量。它具有以下属性：
- ProductId ：（
String，必需） - 表示该产品的唯一标识符的字符串。- sku ：（
String，可选） - 表示库存单位的字符串，允许识别特定项目。- amount ：（
Int，必需） - 此条目代表的项目数。- 价格：（
Float，必需） - 代表一件商品价格的浮点值。货币由包含该项目的 OmetriaBasket 建立- variandId : (
String, 可选) - 与此订单项关联的变体产品的标识符。
OmetriaBasket是一个描述购物篮内容的对象，具有以下属性：
- id : (
String, 可选) - 此购物篮的唯一标识符- currency : (
String, required) - 表示 ISO 4217 三字母货币代码中货币的字符串，例如"USD"、"GBP"- TotalPrice ：（
float，必需） - 表示定价的浮点值。- items : (
Array[OmetriaBasketItem]) - 包含此购物篮中的项目条目的数组。- link : (
String) - 此购物篮的网络或应用内页面的深层链接。可用于发送给用户的通知，例如“忘记结帐？这是您要继续的购物篮：'https://eg.com/basket_url'”。点击该链接后，他们将直接进入购物篮页面。
跟踪用户何时开始结账流程。目前这仅用于统计页面浏览量，在 Ometria 中没有其他作用。
Ometria . trackCheckoutStartedEvent ( 'order_id' ) ;订单已完成并付款：
const items : OmetriaBasketItem [ ] = [
{
productId : 'product-1' ,
sku : 'sku-product-1' ,
quantity : 1 ,
price : 12.0 ,
} ,
] ;
Ometria . trackOrderCompletedEvent ( 'order_id' , {
totalPrice : 12.0 ,
id : 'basket_id_eg' ,
currency : 'USD' ,
items ,
link : 'link_eg' ,
} ) ;当您有足够的有关应用程序将打开的屏幕（或其他目标）的信息时，请使用处理与包含 URL 的通知的交互指南来手动跟踪此事件。
Ometria . trackDeepLinkOpenedEvent ( '/profile' , 'ProfileScreen' ) ;访问者查看您应用程序的“主页”或登陆屏幕。
Ometria . trackHomeScreenViewedEvent ( ) ;访问者点击/点击/查看/突出显示或以其他方式表现出对产品列表的兴趣。这种屏幕包括搜索结果、组、类别、集合中的产品列表或呈现产品列表的任何其他屏幕。
例如，一家商店销售服装，访问者点击“女鞋”即可查看该类别中的产品列表，或者他们搜索“蓝色毛衣”并查看该类别中的产品列表。
该事件应在以下情况触发：
Ometria . trackProductListingViewedEvent ( ) ;跟踪访问者的独立屏幕视图有助于我们跟踪他们与应用程序的互动以及他们在旅程中的位置。
网站上的类似事件是跟踪独立页面浏览量。
常见的电子商务屏幕都有自己的顶级事件：查看的购物篮、查看的产品列表等。
您的应用程序可能具有特定类型的页面，对于营销人员跟踪参与度很有用。
例如，如果您正在进行促销活动，并且查看特定屏幕表明您对促销活动感兴趣，营销人员稍后可能会跟进该促销活动。
要跟踪这些自定义屏幕，请使用屏幕查看事件：
Ometria . trackScreenViewedEvent ( 'OnboardingScreen' , { a : '1' , b : '2' } ) ;您的应用程序可能具有营销团队感兴趣的特定流程或页面。
例如，营销可能希望向注册特定促销活动或与应用程序的按钮或特定元素进行交互的任何用户发送电子邮件或通知。
如果您发送与该操作相对应的自定义事件，他们将能够触发自动化活动。
与营销团队核实具体细节以及他们可能需要什么。特别是如果他们已经使用 Ometria 发送电子邮件，他们就会了解自动化活动和自定义事件。
Ometria . trackCustomEvent ( 'my_custom_type' , { } ) ; SDK 自动跟踪以下事件。
初始化 SDK 就足以利用这些；不需要进一步集成（除非另有说明）。
| 事件 | 描述 |
|---|---|
| 应用程序已安装 | 该应用程序刚刚安装。通常在实际安装应用程序时无法发送，而是仅在第一次启动应用程序时发送。 |
| 应用程序已启动 | 有人刚刚启动了该应用程序。 |
| 应用前景化 | 该应用程序已经启动，但处于后台。它刚刚被带到前台。 |
| 应用背景 | 该应用程序正在使用中，刚刚被发送到后台。 |
| 在应用程序退出状态下收到的通知 | 当应用程序处于退出状态时，系统收到推送通知。 （需要 iOS 上的通知服务扩展） |
| 发生错误 | 客户端发生错误。我们尝试检测我们这边实际通知负载的任何问题，因此我们不希望有任何错误需要反馈给最终用户。 |
为了减少功耗和带宽消耗，Ometria 库不会一一发送事件，除非您要求这样做。
相反，它会在发生以下情况之一时组成在应用程序运行时期间发送到后端的批量事件：
pushtokenRefreshed事件）notificationReceived事件appForegrounded事件appBackgrounded事件您可以通过调用以下命令来请求库随时将所有剩余事件发送到后端：
Ometria . flush ( ) ;您可以完全清除所有已跟踪但尚未刷新的事件。
为此，请调用以下方法：
Ometria . clear ( ) ; 要查看捕获了哪些事件，您可以检查来自 Ometria SDK 的日志（如果启用了日志记录）。您可以过滤“Ometria”一词。 SDK 记录所有发生的事件，并记录刷新，即当它们发送到 Ometria 移动事件 API 时。任何潜在的发送错误（API 问题或事件验证问题）也将在此处可见。
Ometria 使用 Firebase Cloud Messaging 将推送通知发送到移动设备。
因此，您必须使用以下行添加“React-Native Firebase”作为 Ometria 的依赖项：
import firebase from '@react-native-firebase/app' ;
import messaging from '@react-native-firebase/messaging' ;对于Android，请遵循 Firebase ReactNative 教程 Firebase for Android 对于iOS，请遵循 Firebase ReactNative 教程 Firebase for iOS
要使用推送通知，您还需要按照推送通知 ReactNative 指南中的步骤操作
正确设置后，Ometria 可以为您的移动应用程序发送个性化通知。
请按照下列步骤操作：
在继续之前，您必须已经配置：
请阅读第 4 节中有关这些步骤的更多信息。初始化库
对于Android 13 （API 级别 33）及更高版本，您首先必须在 AndroidManifest.xml 文件中声明权限：
< manifest ...>
< uses-permission android : name = " android.permission.POST_NOTIFICATIONS " />
< application ...>
...
</ application >
</ manifest >您必须请求通知权限。您可以使用反应本机权限。
import { requestNotifications , RESULTS } from 'react-native-permissions' ;
...
await requestNotifications ( [ 'alert' , 'sound' , 'badge' ] ) . then ( ( { status } ) => {
if ( status === RESULTS . GRANTED ) {
console . log ( '? Push Notification permissions granted!' ) ;
}
} ) ;在此处查找有关 Android 上的通知运行时权限的更多信息。
Ometria 初始化后，您必须转发 Firebase 推送通知令牌（iOS 和 Android）。
您还必须在每次刷新时将推送通知令牌转发到 Ometria。
import Ometria from 'react-native-ometria' ;
import messaging from '@react-native-firebase/messaging' ;
await Ometria . initializeWithApiToken ( 'API_KEY' , {
notificationChannelname : 'Example Channel Name' , // optional, only for Android
appGroupIdentifier : 'group.com.ometria.sampleRN' , // optional, only for iOS
} ) ;
messaging ( )
. getToken ( )
. then ( ( pushToken ) => Ometria . onNewToken ( pushToken ) ) ;
messaging ( ) . onTokenRefresh ( ( pushToken ) => Ometria . onNewToken ( pushToken ) ) ;订阅您的应用程序在前台应用程序状态时收到的远程消息。您可以使用@react-native-firebase/messaging包中的onMessage方法来执行此操作。
在回调中，您可以使用Ometria.onNotificationReceived让 Ometria SDK 知道已收到远程消息，并将触发notificationReceived事件。如果您想从远程消息中提取 Ometria 数据，请使用Ometria.parseNotification 。
messaging ( ) . onMessage ( async ( remoteMessage ) => {
Ometria . onNotificationReceived ( remoteMessage ) ;
const ometriaData = Ometria . parseNotification ( remoteMessage ) ;
// Use ometriaData
} ) ;如果您实现了这样的自定义解决方案，请不要忘记在处理前台通知的通知交互事件时调用Ometria.onNotificationOpenedApp让已与通知进行交互的 SDK。
为了让 Ometria 准确跟踪 iOS 上应用程序退出和后台状态下收到的所有通知，它需要利用可以访问所有通知的后台服务的功能。
有关如何设置通知服务扩展的完整指南，请参阅添加通知服务扩展目标。
为了让 Ometria 准确跟踪 Android 上应用程序在退出和后台状态下收到的所有通知，您需要提前（在index.js中）订阅您的应用程序在退出和后台状态下收到的远程消息。
Ometria.onAndroidBackgroundMessage会让 Ometria SDK 知道已收到远程消息，并且将会触发notificationReceived事件。它需要 Ometria 令牌才能在后台初始化 SDK。
Platform . OS === 'android' &&
messaging ( ) . setBackgroundMessageHandler ( async ( remoteMessage ) => {
Ometria . onAndroidBackgroundMessage ( {
ometriaToken : 'OMETRIA_KEY'
ometriaOptions : { } ,
remoteMessage ,
} ) ;
} ) ;从版本 2.4.0 开始， Ometria.setBackgroundMessageHandler已被弃用。请改用Ometria.onAndroidBackgroundMessage 。
当用户在后台或退出状态下与通知交互时，您必须让 Ometria SDK 知道已与通知交互并且应用程序已打开。您可以通过使用远程消息作为参数调用Ometria.onNotificationOpenedApp来完成此操作。
// Check if the app was opened from quit state by a notification
messaging ( )
. getInitialNotification ( )
. then ( ( remoteMessage ) => {
if ( remoteMessage ) {
Ometria . onNotificationOpenedApp ( remoteMessage ) ;
}
} ) ;
// Subscribe to the app being opened from background state by a notification
messaging ( ) . onNotificationOpenedApp ( ( remoteMessage ) =>
Ometria . onNotificationOpenedApp ( remoteMessage )
) ;从版本 2.4.0 开始， Ometria.onNotificationInteracted已被弃用。请改用Ometria.onNotificationOpenedApp 。
Ometria 允许您在推送通知的同时发送 URL 和跟踪信息，并允许您在设备上处理它们。当通知打开应用程序时，您可以解析通知远程消息并检查它是否包含深层链接 URL。
const notif = await Ometria . parseNotification ( remoteMessage ) ;
if ( notif ?. deepLinkActionUrl ) {
Ometria . trackDeepLinkOpenedEvent ( notif . deepLinkActionUrl , 'Browser' ) ;
Linking . openURL ( notif . deepLinkActionUrl ) ;
} Ometria.parseNotification返回一个OmetriaNotificationData类型的对象，如下所示：
type OmetriaNotificationData = {
campaignType?: 'trigger; // represents automation campaigns
deepLinkActionUrl?: string;
externalCustomerId?: string;
imageUrl?: string;
sendId?: string;
tracking: { // Can be overridden / added in your automation campaign's settings
utm_medium?: string; // default is "push"
utm_source: string;
utm_campaign: string; // generated from campaign hash and title
om_campagin: string; // generated from campaign hash, campaign version and node id
[key: string]: string | undefined; // additional tracking data you add
};
};
通知服务扩展有两个目的：
要添加扩展，请转到“文件”>“新建”>“目标” ，然后选择“通知服务扩展”>“下一步” 。
一个新项目将显示在您的目标列表中：
接下来，通过更新 podfile 以包含新添加的目标并将 Ometria 指定为依赖项，确保 Ometria SDK 也可用于此新目标。
# move this line before the App target
pod 'GoogleUtilities' , : modular_headers => true
use_frameworks! :linkage => :static
target 'sampleApp' do
# Pods for sampleApp
end
# Add the following lines
target 'NotificationService' do
use_frameworks! :linkage => :static
pod 'Ometria'
end此时，主应用程序和扩展功能作为两个独立的实体，唯一共享的组件是代码。为了使扩展能够获得对与 SDK 相关的数据的读写访问权限，它需要与主要目标位于同一应用程序组中。这将允许主目标和扩展共享数据。
在项目导航器中，选择您的项目，然后转到“签名和功能”并选择左上角的“+ 功能” 。
完成此操作后，签名下方将显示一个新部分。它将允许您添加新的应用程序组。确保选择相关标识符（例如group.[BUNDLE_IDENTIFIER] ），并保留该值，因为实例化 Ometria 时需要它。对通知服务扩展目标重复该过程，您应该可以开始了。
要允许 Ometria 拦截通知，请打开与扩展一起自动创建的NotificationService类，并将内容替换为以下内容：
import UserNotifications
import Ometria
class NotificationService : OmetriaNotificationServiceExtension {
override func instantiateOmetria ( ) -> Ometria ? {
Ometria . initializeForExtension ( appGroupIdentifier : " group.[BUNDLE_IDENTIFIER] " )
}
}最后，在 ReactNative 应用程序中初始化 Ometria 时，您必须使用应用程序组标识符。
import Ometria from 'react-native-ometria' ;
// Ometria init
await Ometria . initializeWithApiToken ( 'API_KEY' , {
notificationChannelName : 'Example Channel Name' , // optional, only for Android
appGroupIdentifier : 'group.[BUNDLE_IDENTIFIER]' , // optional, only for iOS
} ) ;现在，每次在退出状态下收到通知时，您的应用程序都会发出notificationReceived事件，您将能够在 iOS 上显示丰富的内容通知。
有关完整的示例和用例，请参阅示例应用程序。
Ometria 会发送带有指向您网站的 URL 的个性化电子邮件。为了在您的应用程序中打开这些 URL，请确保遵循本指南。
首先，确保您的帐户设置了启用 SSL 的 Ometria 跟踪域。您的电子邮件营销活动可能已经有此域名，但如果没有，请让您的 Ometria 联系人进行设置，他们应该为您提供域名。
请遵循关联域的 ios 文档，然后创建 apple-app-site-association 文件并将其发送给您的 Ometria 联系人。
最后一步是处理应用程序中的 URL 并将用户带到应用程序的相应部分。请注意，您需要实现网站 URL 和应用程序屏幕之间的映射。
另请参阅将推送通知链接到应用程序屏幕。
如果您正在处理指向您网站的普通 URL，您可以将其分解为不同的路径组件和参数。这将允许您获取所需的信息以导航到应用程序中的正确屏幕。
为了让 ReactNative 识别 url 正在打开应用程序，您需要调整 ios 文件夹中的 AppDelegate.m 文件，将以下代码添加到 ./ios/ProjectName 中的 AppDelegate.m
- ( BOOL )application:(UIApplication *)application openURL:( NSURL *)url
sourceApplication:( NSString *)sourceApplication annotation:( id )annotation
{
return [RCTLinkingManager application: application openURL: url
sourceApplication: sourceApplication annotation: annotation];
}
// Only if your app is using [Universal Links](https://developer.apple.com/library/prerelease/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html).
- ( BOOL )application:(UIApplication *)application continueUserActivity:( NSUserActivity *)userActivity
restorationHandler:( void (^)( NSArray * _Nullable))restorationHandler
{
return [RCTLinkingManager application: application
continueUserActivity: userActivity
restorationHandler: restorationHandler];
}对于 Android，请添加以下内容：
< intent-filter android : autoVerify = " true " >
< action android : name = " android.intent.action.VIEW " />
< category android : name = " android.intent.category.DEFAULT " />
< category android : name = " android.intent.category.BROWSABLE " />
< data
android : host = " clickom.omdemo.net "
android : scheme = " https " />
</ intent-filter >到/android/app/src/main/AndroidManifest.xml
但是，Ometria 电子邮件包含模糊的跟踪 URL，在您使用之前，需要将这些 URL 转换回原始 URL，指向您的网站。
