clevertap-react-native 3.0.0 → 3.1.1

package/clevertap-react-native.podspec

@@ -24,7 +24,7 @@ Pod::Spec.new do |s|
     s.dependency 'React-Core'
   end
 
-  s.dependency 'CleverTap-iOS-SDK', '7.0.1'
+  s.dependency 'CleverTap-iOS-SDK', '7.0.2'
 
   if ENV['RCT_NEW_ARCH_ENABLED'] == '1' then
     s.pod_target_xcconfig = {

package/docs/CustomCodeTemplates.md

@@ -0,0 +1,215 @@
+# Custom Code Templates
+
+CleverTap React Native SDK 3.1.0 and above supports a custom presentation of in-app messages. This allows for utilizing the in-app notifications functionality with custom configuration and presentation logic. Two types of templates can be defined through the SDK: Templates and Functions. Templates can contain action arguments while Functions cannot and Functions can be used as actions while Templates cannot. Functions can be either "visual" or "non-visual". "Visual" functions can contain UI logic and will be part of the [In-App queue](#in-App-queue), while "non-visual" functions will be triggered directly when invoked and should not contain UI logic.
+
+## Creating templates and functions
+Templates consist of a name, type, and arguments (and isVisual for Functions). Type and arguments (and isVisual for Functions) are required and names must be unique across the application. The template definitions are validated for correctness and will throw `CustomTemplateException` when an invalid template is created on launching the application. Those exceptions should generally not be caught and template definitions must be valid to be triggered correctly.
+
+The templates are defined in а JSON format with the following scheme:
+```json
+{
+  "TemplateName": {
+    "type": "template",
+    "arguments": {
+      "Argument1": {
+        "type": "string|number|boolean|file|action|object",
+        "value": "val"
+        },
+      "Argument2": {
+        "type": "object",
+        "value": {
+          "Nested1": {
+            "type": "string|number|boolean|object",
+            "value": "val"
+          },
+          "Nested2": {
+            "type": "string|number|boolean|object",
+            "value": "val"
+          }
+        }
+      }
+    }
+  },
+  "functionName": {
+    "type": "function",
+    "isVisual": true|false,
+    "arguments": {
+      "a": {
+      "type": "string|number|boolean|file|object",
+      "value": "val"
+      }
+    }
+  }
+}
+```
+The JSON definitions should be placed in one or more files in the following locations:
+ - Android: in `assets` directory
+ - iOS: in any directory linked to the project
+
+For a working example, see the Example project: `Example/assets/templates.json` and `Example/android/app/src/main/assets/custom/templates.json`.
+
+Optionally the `react-native-assets` package can be utilized to keep both files in sync.
+
+### Arguments
+An `argument` is a structure that represents the configuration of the custom code templates. It consists of a `type` and a `value`.
+The supported argument types are:
+- Primitives - `boolean`, `number`, and `string`. They must have a default value which would be used if no other value is configured for the notification.
+- `object` - An `Object` where keys are the argument names and values are ```Arguments``` with supported primitive values.
+- `file` - a file argument that will be downloaded when the template is triggered. Files don't have default values.
+- `action` - an action argument that could be a function template or a built-in action like ‘close’ or ‘open url’. Actions don't have default values.
+
+#### Hierarchical arguments
+You can group arguments by either using an `object` argument or indicating the group in the argument's name by using a "." symbol. Both definitions are treated the same. `file` and `action` type arguments can only be added to a group by specifying the group in the argument's name.
+
+The following code snippets define identical arguments:
+```json
+"arguments": {
+    "map": {
+        "type": "object",
+        "value": {
+            "a": {
+                "type": "number",
+                "value": 5
+            },
+            "b": {
+                "type": "number",
+                "value": 6
+            }
+        }
+    }
+}
+```
+and
+```json
+"arguments": {
+    "map.a": {
+        "type": "number",
+        "value": 5
+    },
+    "map.b": {
+        "type": "number",
+        "value": 6
+    }
+}
+```
+
+### Template definition example
+```json
+"Example template": {
+    "type": "template",
+    "arguments": {
+        "boolArg": {
+            "type": "boolean",
+            "value": false
+        },
+        "stringArg": {
+            "type": "string",
+            "value": "Default"
+        },
+        "mapArg": {
+            "type": "object",
+            "value": {
+                "int": {
+                    "type": "number",
+                    "value": 0
+                },
+                "string": {
+                    "type": "string",
+                    "value": "Default"
+                }
+            }
+        },
+        "actionArg": {
+            "type": "action"
+        },
+        "fileArg": {
+            "type": "file"
+        }
+    }
+}
+```
+
+## Registering custom templates
+
+Templates must be registered within the native applications:
+
+### For Android
+Call `CleverTapCustomTemplates.registerCustomTemplates` in your `Application.onCreate` method.
+ - If you are extending `CleverTapApplication` add this line before calling `super.onCreate()`:
+```java
+public class MainApplication extends CleverTapApplication {
+    @Override
+    public void onCreate() {
+        CleverTapCustomTemplates.registerCustomTemplates(this, "templateDefinitionsFileInAssets.json");
+        super.onCreate();
+    }
+}
+```
+ - Otherwise add the line before calling `CleverTapRnAPI.initReactNativeIntegration(this)`:
+```java
+public class MainApplication extends Application {
+    @Override
+    public void onCreate() {
+        ActivityLifecycleCallback.register(this);
+        super.onCreate();
+        CleverTapCustomTemplates.registerCustomTemplates(this, "templateDefinitionsFileInAssets.json");
+        CleverTapRnAPI.initReactNativeIntegration(this);
+    }
+}
+```
+
+### For iOS
+Call `[CleverTapReactCustomTemplates registerCustomTemplates]` in your `AppDelegate.didFinishLaunchingWithOptions` before calling `[CleverTap autoIntegrate]`:
+```objc
+@implementation AppDelegate
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+  [CleverTapReactCustomTemplates registerCustomTemplates:@"templates", nil];
+  [CleverTap autoIntegrate];
+  [[CleverTapReactManager sharedInstance] applicationDidLaunchWithOptions:launchOptions];
+
+  return [super application:application didFinishLaunchingWithOptions:launchOptions];
+}
+```
+
+## Syncing in-app templates to the dashboard
+
+For the templates to be usable in campaigns they must be synced with the dashboard. When all templates and functions are defined and registered in the SDK, they can be synced by calling `CleverTap.syncCustomTemplates()` or `CleverTap.syncCustomTemplatesInProd()` in your React application. The syncing can only be done in debug builds and with an SDK user marked as a "test user". We recommend only calling this function while developing the templates and deleting the invocation in release builds.
+
+## Presenting templates
+
+When a custom template is triggered, the corresponding event `CleverTap.CleverTapCustomTemplatePresent` or `CleverTap.CleverTapCustomFunctionPresent` will be raised. Applications with custom templates or functions must subscribe to those events through `CleverTap.addListener` where the event data will be the template's name. When the event handler is invoked, this template will be considered "active" until `CleverTap.customTemplateSetDismissed(templateName)` is called. While a template is "active" the following functions can be used:
+
+- Obtain argument values by using the appropriate `customTemplateGet*Arg(templateName: string, argName: string)` methods.
+- Trigger actions by their name through `CleverTap.customTemplateRunAction(templateName: string, argName: string)`.
+- Set the state of the template invocation. `CleverTap.customTemplateSetPresented(templateName: string)` and `CleverTap.customTemplateSetDismissed(templateName: string)` notify the SDK of the state of the current template invocation. The presented state is when an in-app is displayed to the user and the dismissed state is when the in-app is no longer displayed.
+
+Only one visual template or other InApp message can be displayed at a time by the SDK and no new messages can be shown until the current one is dismissed.
+
+Applications should also subscribe to `CleverTap.CleverTapCustomTemplateClose` which will be raised when a template should be closed (this could occur when an action of type "close" is triggered). Use this listener to remove the UI associated with the template and call `CleverTap.customTemplateSetDismissed(templateName)` to close it.
+
+### Example
+
+```js
+CleverTap.addListener(CleverTap.CleverTapCustomTemplatePresent, templateName => {
+    // show the UI for the template and call customTemplateSetDismissed when it is closed
+    showTemplateUi({
+        template: templateName,
+        onClose: ()=> {
+            CleverTap.customTemplateSetDismissed(templateName);
+        }
+    });
+    // call customTemplateSetPresented when the UI has become visible to the user
+   CleverTap.customTemplateSetPresented(templateName);
+});
+
+CleverTap.addListener(CleverTap.CleverTapCustomTemplateClose, templateName => {
+    // close the corresponding UI before calling customTemplateSetDismissed
+    CleverTap.customTemplateSetDismissed(templateName);
+});
+```
+
+### In-App queue
+When an in-app needs to be shown it is added to a queue (depending on its priority) and is displayed when all messages before it have been dismissed. The queue is saved in the storage and kept across app launches to ensure all messages are displayed when possible. The custom code in-apps behave in the same way. They will be triggered once their corresponding notification is the next one in the queue to be shown. However since the control of the dismissal is left to the application's code, the next in-app message will not be displayed until the current code template has called `CleverTap.customTemplateSetDismissed(templateName)`
+
+### File downloading and caching
+File arguments are automatically downloaded and are ready for use when an in-app template is presented. The files are downloaded when a file argument has changed and this file is not already cached. For client-side in-apps, this happens at App Launch and is retried if needed when an in-app should be presented. For server-side in-apps, the file downloading happens only before presenting the in-app. If any of the file arguments of an in-app fails to be downloaded, the whole in-app is skipped and the custom template will not be triggered.

package/docs/Variables.md

@@ -27,6 +27,14 @@ let variables = {
 CleverTap.defineVariables(variables);
 ```
 
+# Define File Variables
+
+CleverTap React Native SDK supports file types for variables from version `3.1.0`. Supported file types include but are not limited to images (jpg, jpeg, png, gif), text files, and PDFs.
+
+```javascript
+CleverTap.defineFileVariable("fileVariable");
+```
+
 # Setup Callbacks
 
 CleverTap React Native SDK provides several callbacks for the developer to receive feedback from the SDK. You can use them as per your requirement, using all of them is not mandatory. They are as follows:
@@ -35,6 +43,13 @@ CleverTap React Native SDK provides several callbacks for the developer to recei
 - `onVariablesChanged`
 - `onValueChanged`
 
+From version `3.1.0` onwards, the following callbacks are also supported:
+
+- `onOneTimeVariablesChanged`
+- `onVariablesChangedAndNoDownloadsPending`
+- `onceVariablesChangedAndNoDownloadsPending`
+- `onFileValueChanged`
+
 ## Status of Variables Fetch Request
 
 This method provides a boolean flag to ensure that the variables are successfully fetched from the server.
@@ -55,6 +70,16 @@ CleverTap.onVariablesChanged((variables) => {
 });
 ```
 
+## `onOneTimeVariablesChanged`
+
+This callback is invoked once when variables are initialized with a value or changed with a new server value. Callback is triggered only once on app start, or when added if server values are already received
+
+```javascript
+ CleverTap.onOneTimeVariablesChanged((variables) => {
+    console.log('onOneTimeVariablesChanged: ', variables);
+});
+```
+
 ## `onValueChanged`
 
 This callback is invoked when the value of the variable changes. You must provide the name of the variable whose value needs to be observed.
@@ -65,6 +90,36 @@ CleverTap.onValueChanged('reactnative_var_string', (variable) => {
 });
 ```
 
+## `onVariablesChangedAndNoDownloadsPending`
+
+This callback is invoked when variable values are changed and the files associated with it are downloaded and ready to be used. Callback is triggered each time new values are fetched and downloaded.
+
+```javascript
+CleverTap.onVariablesChangedAndNoDownloadsPending((variables) => {
+    console.log('onVariablesChangedAndNoDownloadsPending', variables);
+});
+```
+
+## `onceVariablesChangedAndNoDownloadsPending`
+
+This callback is invoked only once when variable values are changed and the files associated with it are downloaded and ready to be used. Callback is triggered only once for when new values are fetched and downloaded 
+
+```javascript
+CleverTap.onceVariablesChangedAndNoDownloadsPending((variables) => {
+    console.log('onceVariablesChangedAndNoDownloadsPending', variables);
+});
+```
+
+## `onFileValueChanged`
+
+This callback is registered per file variable. It is called when the file associated with the file variable is downloaded and ready to be used.
+
+```javascript
+CleverTap.onFileValueChanged('fileVariable', (variable) => {
+    console.log('onFileValueChanged: ', variable);
+});
+```
+
 # Sync Defined Variables
 
 After defining your variables in the code, you must send/sync variables to the server. To do so, the app must be in DEBUG mode and mark a particular CleverTap user profile as a test profile from the CleverTap dashboard. [Learn how to mark a profile as **Test Profile**](https://developer.clevertap.com/docs/concepts-user-profiles#mark-a-user-profile-as-a-test-profile)

package/docs/integration.md

@@ -30,25 +30,21 @@ Note: Need to use **@import CleverTapSDK;** instead of **#import <CleverTap-iOS-
 2. Add CleverTapPackage to the packages list in MainApplication.java (`android/app/src/[...]/MainApplication.java`)
     ```java
     // ...
-
+    
     // CleverTap imports
-    import com.clevertap.android.sdk.ActivityLifecycleCallback;
     import com.clevertap.react.CleverTapPackage;
-    import com.clevertap.react.CleverTapRnAPI;
-
-
+    
     //...
-
+    
     // add CleverTapPackage to react-native package list
-    @Override
-      protected List<ReactPackage> getPackages() {
-        List<ReactPackage> packages = new PackageList(this).getPackages();
-        // Packages that cannot be autolinked yet can be added manually here, for
-        // example:
-        packages.add(new CleverTapPackage());// only needed when not auto-linking
-        return packages;
-        
-    }
+        @Override
+        protected List<ReactPackage> getPackages() {
+            List<ReactPackage> packages = new PackageList(this).getPackages();
+            // Packages that cannot be autolinked yet can be added manually here, for
+            // example:
+            packages.add(new CleverTapPackage());// only needed when not auto-linking
+            return packages;
+        }
     ```
 
 3. Initialise Clevertap ReactNative Integration - This adds support for `ClevertapPushNotiificationClicked` from killed state and registers the `ActivityLifecycleCallback`
@@ -60,52 +56,52 @@ Note: Need to use **@import CleverTapSDK;** instead of **#import <CleverTap-iOS-
     import com.clevertap.android.sdk.CleverTapAPI;
     import com.clevertap.android.sdk.CleverTapAPI.LogLevel;
     // ...
-
-        public class MainApplication implements ReactApplication {
-            // ...
-
-            @Override
-            public void onCreate() {
-                CleverTapAPI.setDebugLevel(LogLevel.VERBOSE);
-                ActivityLifecycleCallback.register(this);
-                CleverTapRnAPI.initReactNativeIntegration(this);
-                super.onCreate();
-                // ...
-            }
-
+    
+    public class MainApplication implements ReactApplication 
+    {
         // ...
+    
+        @Override
+        public void onCreate() {
+            CleverTapAPI.setDebugLevel(LogLevel.VERBOSE);
+            ActivityLifecycleCallback.register(this);
+            CleverTapRnAPI.initReactNativeIntegration(this);
+            super.onCreate();
+            // ...
         }
+    
+    // ...
+    }
     ```
 
 <div style="text-align:center; font-size: larger; font-weight: bold;">OR</div>
 <br>
 
-
 - From clevertap-react-native **v3.0.0** onwards developers can make their `Application` class extend `CleverTapApplication` to support out of the box integration. Before **v3.0.0** developers were forced to register activity lifecycle in their `Application` class manually which is being abstract out in `CleverTapApplication` class.
  
     ```java
-  import com.clevertap.react.CleverTapApplication;
-  import com.clevertap.android.sdk.ActivityLifecycleCallback;
-  import com.clevertap.android.sdk.CleverTapAPI;
-  import com.clevertap.android.sdk.CleverTapAPI.LogLevel;
-   // other imports
-   
-   public class MainApplication extends CleverTapApplication
+    import com.clevertap.react.CleverTapApplication;
+    import com.clevertap.android.sdk.ActivityLifecycleCallback;
+    import com.clevertap.android.sdk.CleverTapAPI;
+    import com.clevertap.android.sdk.CleverTapAPI.LogLevel;
+    // other imports
+    
+    public class MainApplication extends CleverTapApplication
            implements ActivityLifecycleCallbacks, ReactApplication
-   {
+    {
         // ...
         @Override
-          public void onCreate() {
-              CleverTapAPI.setDebugLevel(LogLevel.VERBOSE);
-              ActivityLifecycleCallback.register(this); // Not required for v3.0.0+
-              super.onCreate();
-              // ...
-          }
-   }
+        public void onCreate() {
+          CleverTapAPI.setDebugLevel(LogLevel.VERBOSE);
+          ActivityLifecycleCallback.register(this); // Not required for v3.0.0+
+          super.onCreate();
+          // ...
+        }
+    }
     ```
 4. <a name="step4"></a> Optionally override onCreate in MainActivity.java to notify CleverTap of a launch deep link  (`android/app/src/[...]/MainActivity.java`)
     ```java
-    import com.clevertap.react.CleverTapModule;
+    import com.clevertap.react.CleverTapRnAPI;
     import android.os.Bundle;
    
     
@@ -115,7 +111,7 @@ Note: Need to use **@import CleverTapSDK;** instead of **#import <CleverTap-iOS-
         @Override
         protected void onCreate(Bundle savedInstanceState) {
             super.onCreate(savedInstanceState);
-            CleverTapRnAPI.setInitialUri(getIntent().getData());
+            CleverTapRnAPI.setInitialUri(getIntent().getData()); // From v3.0.0+
     	}
 
         // ...

package/ios/CleverTapReact/CleverTapReact.h

@@ -18,7 +18,14 @@ static NSString *const kCleverTapPushNotificationClicked = @"CleverTapPushNotifi
 static NSString *const kCleverTapPushPermissionResponseReceived = @"CleverTapPushPermissionResponseReceived";
 static NSString *const kCleverTapInAppNotificationShowed = @"CleverTapInAppNotificationShowed";
 static NSString *const kCleverTapOnVariablesChanged = @"CleverTapOnVariablesChanged";
+static NSString *const kCleverTapOnOneTimeVariablesChanged = @"CleverTapOnOneTimeVariablesChanged";
 static NSString *const kCleverTapOnValueChanged = @"CleverTapOnValueChanged";
+static NSString *const kCleverTapOnVariablesChangedAndNoDownloadsPending = @"CleverTapOnVariablesChangedAndNoDownloadsPending";
+static NSString *const kCleverTapOnceVariablesChangedAndNoDownloadsPending = @"CleverTapOnceVariablesChangedAndNoDownloadsPending";
+static NSString *const kCleverTapOnFileValueChanged = @"CleverTapOnFileValueChanged";
+static NSString *const kCleverTapCustomTemplatePresent = @"CleverTapCustomTemplatePresent";
+static NSString *const kCleverTapCustomFunctionPresent = @"CleverTapCustomFunctionPresent";
+static NSString *const kCleverTapCustomTemplateClose = @"CleverTapCustomTemplateClose";
 static NSString *const kXPS = @"XPS";
 
 #ifdef RCT_NEW_ARCH_ENABLED
@@ -31,4 +38,4 @@ static NSString *const kXPS = @"XPS";
 
 + (void)sendEventOnObserving:(NSString *)name body:(id)body;
 
-@end
+@end