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，指向您的網站。
