Documentation for API changes

documentation/CONFIGURATION.md

@@ -18,6 +18,7 @@ Minimal required configuration is simple:
 import Exponea from 'react-native-exponea-sdk'
 
 Exponea.configure({
+  projectToken: "your-project-token",
   projectToken: "your-project-token",
   authorizationToken: "your-authorization-token",
   // default baseUrl value is https://api.exponea.com

documentation/IN_APP_MESSAGES.md

@@ -20,3 +20,55 @@ In-app messages are triggered when an event is tracked based on conditions setup
 If your application decides to present another UIViewController/start a new Activity right at the same time a race condition is created and the message might be displayed and immediately dismissed. Keep this in mind if the logs tell you your message was displayed but you don't see it.
 
 > Show on `App load` displays in-app message when a `session_start` event is tracked. If you close and quickly reopen the app, it's possible that the session did not timeout and message won't be displayed. If you use manual session tracking, the message won't be displayed unless you track `session_start` event yourself.
+
+Message is able to be shown only if it is loaded and also its image is loaded too. In case that message is not yet fully loaded (including its image) then the request-to-show is registered in SDK for that message so SDK will show it after full load.
+Due to prevention of unpredicted behaviour (i.e. image loading takes too long) that request-to-show has timeout of 3 seconds.
+
+> If message loading hits timeout of 3 seconds then message will be shown on 'next request'. For example the 'session_start' event triggers a showing of message that needs to be fully loaded but it timeouts, then message will not be shown. But it will be ready for next `session_start` event so it will be shown on next 'application run'.
+
+### In-app images caching
+To reduce the number of API calls and fetching time of in-app messages, SDK is caching the images displayed in messages. Therefore, once the SDK downloads the image, an image with the same URL may not be downloaded again, and will not change, since it was already cached. For this reason, we recommend always using different URLs for different images.
+
+### In-app messages loading
+In-app messages reloading is triggered by any case of:
+- when `Exponea.identifyCustomer` is called
+- when `Exponea.anonymize` is called
+- when any event is tracked (except Push clicked, opened or session ends) and In-app messages cache is older then 30 minutes from last load
+  Any In-app message images are preloaded too so message is able to be shown after whole process is finished. Please considers it while testing of In-app feature.
+  It is common behaviour that if you change an In-app message data on platform then this change is reflected in SDK after 30 minutes due to usage of messages cache. Do call `Exponea.identifyCustomer` or `Exponea.anonymize` if you want to reflect changes immediately.
+
+### Custom in-app message actions
+If you want to override default SDK behavior, when in-app message action is performed (button is clicked, a message is closed), or you want to add your code to be performed along with code executed by the SDK, you can set up `inAppMessageActionCallback` on Exponea instance.
+
+```typescript
+// If overrideDefaultBehavior is set to true, default in-app action will not be performed ( e.g. deep link )
+let overrideDefaultBehavior = false;
+// If trackActions is set to false, click and close in-app events will not be tracked automatically
+let trackActions = true;
+Exponea.setInAppMessageCallback(false, true, (action) => {
+    console.log('InApp action received - App.tsx');
+    // Here goes your code
+    // On in-app click, the button contains button text and button URL, and the interaction is true
+    // On in-app close by user interaction, the button is null and the interaction is true
+    // On in-app close by non-user interaction (i.e. timeout), the button is null and the interaction is false
+});
+```
+
+If you set `trackActions` to **false** but you still want to track click/close event under some circumstances, you can call Exponea methods `trackInAppMessageClick` or `trackInAppMessageClose` in the action method:
+
+```typescript
+Exponea.setInAppMessageCallback(false, false, (action) => {
+    console.log('InApp action received - App.tsx');
+    if (<your-special-condition>) {
+        if (interaction) {
+            Exponea.trackInAppMessageClick(action.message, action.button?.text, action.button?.url)
+        } else {
+            Exponea.trackInAppMessageClose(action.message)
+        }
+    }
+});
+```
+
+Method `trackInAppMessageClose` will track a 'close' event with 'interaction' field of TRUE value by default. You are able to use a optional parameter 'interaction' of this method to override this value.
+
+> The behaviour of `trackInAppMessageClick` and `trackInAppMessageClose` may be affected by the tracking consent feature, which in enabled mode considers the requirement of explicit consent for tracking. Read more in [tracking consent documentation](./TRACKING_CONSENT.md).

documentation/PAYMENT.md

@@ -0,0 +1,19 @@
+## 🔍 Payments
+
+Exponea SDK has a convenience method `trackPaymentEvent` to help you track information about a payment for product/service within the application.
+```
+trackPaymentEvent(params: Record<string, string>): Promise<void>;
+```
+To support multiple platforms and use-cases, SDK defines Map of values that contains basic information about the purchase.
+#### 💻 Usage
+
+```typescript
+Exponea.trackPaymentEvent({
+      "brutto": "10.0",
+      "currency": "USD",
+      "payment_system": "CardHolder",
+      "item_id": "abcd1234",
+      "product_title": "Best product",
+      "receipt": "INV_12345"
+    });
+```

documentation/TRACKING_CONSENT.md

@@ -0,0 +1,77 @@
+## Tracking consent
+
+Based on the recent judgment (May 2022) made by the Federal Court of Justice in Germany (Bundesgerichtshof – BGH)
+regarding the EU Datenschutz Grundverordnung (EU-GDPR), all access to data on the affected person’s device would
+require explicit consent. For more info see [Configuration of the tracking consent categories](https://documentation.bloomreach.com/engagement/docs/configuration-of-tracking-consent).
+
+The SDK is adapted to the rules and is controlled according to the data received from the Push Notifications or InApp Messages.
+If the tracking consent feature is disabled, the Push Notifications and InApp Messages data do not contain 'hasTrackingConsent' and their tracking behaviour has not been changed, so if the attribute 'hasTrackingConsent' is not present in data, SDK considers it as 'true'.
+If the tracking consent feature is enabled, Push Notifications and InApp Messages data contain 'hasTrackingConsent' and the SDK tracks events according to the boolean value of this field.
+
+Disallowed tracking consent ('hasTrackingConsent' provided with 'false' value) can be overridden with URL query param 'xnpe_force_track' with 'true' value.
+
+### Event for push notification delivery
+
+Event is normally tracked by calling `Exponea.trackDeliveredPush`. This method is tracking a delivered event only if:
+
+* Tracking consent feature is disabled
+* Tracking consent feature is enabled and 'hasTrackingConsent' has 'true' value
+
+If you are using `Exponea.trackDeliveredPush` method manually and you want to avoid to consider tracking, you may use `Exponea.trackDeliveredPushWithoutTrackingConsent` instead. This method will do track event ignoring tracking consent state.
+
+### Event for clicked push notification
+
+Event is normally tracked by calling `Exponea.trackClickedPush`. This method is tracking
+a clicked event only if:
+
+* Tracking consent feature is disabled
+* Tracking consent feature is enabled and 'hasTrackingConsent' has 'true' value
+* Action URL contains 'xnpe_force_track' with 'true' value independently from 'hasTrackingConsent' value
+
+> Event that is tracked because of `xnpe_force_track` (forced tracking) will contains an additional property `tracking_forced` with value `true`
+
+If you are using `Exponea.trackClickedPush` method manually and you want to avoid to consider tracking, you may use `Exponea.trackClickedPushWithoutTrackingConsent` instead. This method will do track event ignoring tracking consent state.
+
+### Event for clicked InApp Message
+
+Event is normally tracked by calling `Exponea.trackInAppMessageClick`. This method is tracking
+a clicked event only if:
+
+* Tracking consent feature is disabled
+* Tracking consent feature is enabled and 'hasTrackingConsent' has 'true' value
+* Action URL contains 'xnpe_force_track' with 'true' value independently from 'hasTrackingConsent' value
+
+> Event that is tracked because of `xnpe_force_track` (forced tracking) will contains an additional property `tracking_forced` with value `true`
+
+If you are using `Exponea.trackInAppMessageClick` method manually and you want to avoid to consider tracking, you may use `Exponea.trackInAppMessageClickWithoutTrackingConsent` instead. This method will do track event ignoring tracking consent state.
+
+### Event for closed InApp Message
+
+Event is normally tracked by calling `Exponea.trackInAppMessageClose`. This method is tracking a delivered event only if:
+
+* Tracking consent feature is disabled
+* Tracking consent feature is enabled and 'hasTrackingConsent' has 'true' value
+
+If you are using `Exponea.trackInAppMessageClose` method manually and you want to avoid to consider tracking, you may use `Exponea.trackInAppMessageCloseWithoutTrackingConsent` instead. This method will do track event ignoring tracking consent state.
+
+### Event for opened AppInbox Message
+
+Event is normally tracked by calling `Exponea.trackAppInboxOpened`. This method is tracking a delivered event only if:
+
+* Tracking consent feature is disabled
+* Tracking consent feature is enabled and 'hasTrackingConsent' has 'true' value
+* AppInbox has been loaded and given MessageItem is listed in AppInbox
+
+If you are using `Exponea.trackAppInboxOpened` method manually and you want to avoid to consider tracking, you may use `Exponea.trackAppInboxOpenedWithoutTrackingConsent` instead. This method will do track event ignoring tracking consent state.
+
+### Event for clicked AppInbox Message action
+
+Event is normally tracked by calling `Exponea.trackAppInboxClick`. This method is tracking a clicked event only if:
+
+* Tracking consent feature is disabled
+* Tracking consent feature is enabled and 'hasTrackingConsent' has 'true' value
+* Action URL contains 'xnpe_force_track' with 'true' value independently from 'hasTrackingConsent' value
+
+> Event that is tracked because of `xnpe_force_track` (forced tracking) will contains an additional property `tracking_forced` with value `true`
+
+If you are using `Exponea.trackAppInboxClick` method manually and you want to avoid to consider tracking, you may use `Exponea.trackAppInboxClickWithoutTrackingConsent` instead. This method will do track event ignoring tracking consent state.