feat: support app flows APIs (#1138)

Author: abdelhamid-f-nasser

.eslintrc.js

@@ -1,7 +1,7 @@
 /** @type {import('eslint').ESLint.ConfigData} */
 module.exports = {
   extends: '@react-native-community',
-  plugins: ['prettier', 'jest'],
+  plugins: ['prettier', 'jest', 'jsdoc'],
   overrides: [
     {
       // Jest Overrides
@@ -27,6 +27,7 @@ module.exports = {
     },
   ],
   rules: {
+    'jsdoc/no-undefined-types': 'warn',
     'prettier/prettier': 'error',
     'prefer-const': 'error',
   },

CHANGELOG.md

@@ -17,6 +17,11 @@
 
 - Adds symbol files upload script ([#1137](https://github.com/Instabug/Instabug-React-Native/pull/1137))
 - Support enabling NDK crash capturing on Android ([#1132](https://github.com/Instabug/Instabug-React-Native/pull/1132)).
+- Add support for App Flows APIs `APM.startFlow`, `APM.setFlowAttribute` and `APM.endFlow` ([#1138](https://github.com/Instabug/Instabug-React-Native/pull/1138)).
+
+### Deprecated
+
+- Deprecate Execution Traces APIs `APM.startExecutionTrace`, `Trace.end` and `Trace.setAttribute` in favor of the new App Flows APIs ([#1138](https://github.com/Instabug/Instabug-React-Native/pull/1138)).
 
 ### Changed
 

android/src/main/java/com/instabug/reactlibrary/RNInstabugAPMModule.java

@@ -4,6 +4,7 @@
 import android.os.SystemClock;
 import android.util.Log;
 
+import androidx.annotation.NonNull;
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactContextBaseJavaModule;
@@ -29,6 +30,8 @@ public class RNInstabugAPMModule extends ReactContextBaseJavaModule {
     public RNInstabugAPMModule(ReactApplicationContext reactApplicationContext) {
         super(reactApplicationContext);
     }
+
+    @Deprecated
     HashMap<String, ExecutionTrace> traces = new HashMap<String, ExecutionTrace>();
 
     @Nonnull
@@ -121,10 +124,92 @@ public void run() {
         });
     }
 
+    /**
+     * Starts an AppFlow with the specified name.
+     * <br/>
+     * On starting two flows with the same name the older flow will end with force abandon end reason.
+     * AppFlow name cannot exceed 150 characters otherwise it's truncated,
+     * leading and trailing whitespaces are also ignored.
+     *
+     * @param name AppFlow name. It can not be empty string or null.
+     *             Starts a new AppFlow, if APM is enabled, feature is enabled
+     *             and Instabug SDK is initialised.
+     */
+    @ReactMethod
+    public void startFlow(@NonNull final String name) {
+        MainThreadHandler.runOnMainThread(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    APM.startFlow(name);
+                } catch (Exception e) {
+                    e.printStackTrace();
+                }
+            }
+        });
+    }
+
+    /**
+     * Sets custom attributes for AppFlow with a given name.
+     * <br/>
+     * Setting an attribute value to null will remove its corresponding key if it already exists.
+     * <br/>
+     * Attribute key name cannot exceed 30 characters.
+     * Leading and trailing whitespaces are also ignored.
+     * Does not accept empty strings or null.
+     * <br/>
+     * Attribute value name cannot exceed 60 characters,
+     * leading and trailing whitespaces are also ignored.
+     * Does not accept empty strings.
+     * <br/>
+     * If a trace is ended, attributes will not be added and existing ones will not be updated.
+     * <br/>
+     *
+     * @param name  AppFlow name. It can not be empty string or null
+     * @param key   AppFlow attribute key. It can not be empty string or null
+     * @param value AppFlow attribute value. It can not be empty string. Null to remove attribute
+     */
+    @ReactMethod
+    public void setFlowAttribute(@NonNull final String name, @NonNull final String key, final String value) {
+        MainThreadHandler.runOnMainThread(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    APM.setFlowAttribute(name, key, value);
+                } catch (Exception e) {
+                    e.printStackTrace();
+                }
+            }
+        });
+    }
+
+    /**
+     * Ends AppFlow with a given name.
+     *
+     * @param name AppFlow name to be ended. It can not be empty string or null
+     */
+    @ReactMethod
+    public void endFlow(@NonNull final String name) {
+        MainThreadHandler.runOnMainThread(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    APM.endFlow(name);
+                } catch (Exception e) {
+                    e.printStackTrace();
+                }
+            }
+        });
+    }
+
     /**
      * Starts an execution trace
+     *
      * @param name string name of the trace.
+     *
+     * @deprecated see {@link #startFlow(String)}
      */
+    @Deprecated
     @ReactMethod
     public void startExecutionTrace(final String name, final String id, final Promise promise) {
         MainThreadHandler.runOnMainThread(new Runnable() {
@@ -148,10 +233,14 @@ public void run() {
 
     /**
      * Adds a new attribute to trace
-     * @param id String id of the trace.
+     *
+     * @param id    String id of the trace.
      * @param key   attribute key
      * @param value attribute value. Null to remove attribute
+     *
+     * @deprecated see {@link #setFlowAttribute}
      */
+    @Deprecated
     @ReactMethod
     public void setExecutionTraceAttribute(final String id, final String key, final String value) {
         MainThreadHandler.runOnMainThread(new Runnable() {
@@ -168,8 +257,12 @@ public void run() {
 
     /**
      * Ends a trace
+     *
      * @param id string id of the trace.
+     *
+     * @deprecated see {@link #endFlow}
      */
+    @Deprecated
     @ReactMethod
     public void endExecutionTrace(final String id) {
         MainThreadHandler.runOnMainThread(new Runnable() {

android/src/test/java/com/instabug/reactlibrary/RNInstabugAPMModuleTest.java

@@ -125,6 +125,37 @@ public void givenTruesetEnabled_whenQuery_thenShouldCallNativeApiWithEnabled() {
         verify(promise).resolve(any());
     }
 
+    @Test
+    public void testStartFlow() {
+        String appFlowName = "appFlowName";
+
+        apmModule.startFlow(appFlowName);
+
+        mockAPM.verify(() -> APM.startFlow(appFlowName));
+        mockAPM.verifyNoMoreInteractions();
+    }
+
+    @Test
+    public void testEndFlow() {
+        String appFlowName = "appFlowName";
+
+        apmModule.endFlow(appFlowName);
+
+        mockAPM.verify(() -> APM.endFlow(appFlowName));
+        mockAPM.verifyNoMoreInteractions();
+    }
+
+    @Test
+    public void testSetFlowAttribute() {
+        String appFlowName = "appFlowName";
+        String flowAttributeKey = "attributeKey";
+        String flowAttributeValue = "attributeValue";
+        apmModule.setFlowAttribute(appFlowName, flowAttributeKey, flowAttributeValue);
+
+        mockAPM.verify(() -> APM.setFlowAttribute(appFlowName, flowAttributeKey, flowAttributeValue));
+        mockAPM.verifyNoMoreInteractions();
+    }
+
     // @Test
     // public void givenString$setExecutionTraceAttribute_whenQuery_thenShouldCallNativeApiWithIntArgs() {
     //     // given

examples/default/ios/InstabugTests/InstabugAPMTests.m

@@ -62,15 +62,15 @@ - (void) testSetAPMEnabled {
 - (void) testSetAppLaunchEnabled {
   id mock = OCMClassMock([IBGAPM class]);
   BOOL isEnabled = YES;
-  
+
   OCMStub([mock setColdAppLaunchEnabled:isEnabled]);
   [self.instabugBridge setAppLaunchEnabled:isEnabled];
   OCMVerify([mock setColdAppLaunchEnabled:isEnabled]);
 }
 
 - (void) testEndAppLaunch {
   id mock = OCMClassMock([IBGAPM class]);
-  
+
   OCMStub([mock endAppLaunch]);
   [self.instabugBridge endAppLaunch];
   OCMVerify([mock endAppLaunch]);
@@ -79,7 +79,7 @@ - (void) testEndAppLaunch {
 - (void) testSetAutoUITraceEnabled {
   id mock = OCMClassMock([IBGAPM class]);
   BOOL isEnabled = YES;
-  
+
   OCMStub([mock setAutoUITraceEnabled:isEnabled]);
   [self.instabugBridge setAutoUITraceEnabled:isEnabled];
   OCMVerify([mock setAutoUITraceEnabled:isEnabled]);
@@ -91,7 +91,7 @@ - (void) testStartExecutionTrace {
   NSString* traceKey = @"1";
   RCTPromiseResolveBlock resolve = ^(id result) {};
   RCTPromiseRejectBlock reject = ^(NSString *code, NSString *message, NSError *error) {};
-  
+
   OCMStub([mock startExecutionTraceWithName:traceName]);
   [self.instabugBridge startExecutionTrace:traceName :traceKey :resolve :reject];
   OCMVerify([mock startExecutionTraceWithName:traceName]);
@@ -107,10 +107,10 @@ - (void) testSetExecutionTraceAttribute {
   IBGExecutionTrace * trace = [IBGExecutionTrace alloc];
   id mock = OCMClassMock([IBGAPM class]);
   id traceMock = OCMPartialMock(trace);
-  
+
   OCMStub([mock startExecutionTraceWithName:traceName]).andReturn(trace);
   [self.instabugBridge startExecutionTrace:traceName :traceId :resolve :reject];
-  
+
   OCMStub([traceMock setAttributeWithKey:traceKey value:traceValue]);
   [self.instabugBridge setExecutionTraceAttribute:traceId :traceKey :traceValue];
   OCMVerify([traceMock setAttributeWithKey:traceKey value:traceValue]);
@@ -127,24 +127,50 @@ - (void) testEndExecutionTrace {
 
   OCMStub([apmMock startExecutionTraceWithName:traceName]).andReturn(trace);
   [self.instabugBridge startExecutionTrace:traceName :traceId :resolve :reject];
-  
+
   OCMStub([traceMock end]);
   [self.instabugBridge endExecutionTrace:traceId];
   OCMVerify([traceMock end]);
 }
 
+- (void) testStartFlow {
+  id mock = OCMClassMock([IBGAPM class]);
+  NSString* appFlowName = @"APP_Flow_1";
+
+  [self.instabugBridge startFlow:appFlowName];
+  OCMVerify([mock startFlowWithName:appFlowName]);
+}
+
+- (void) testEndFlow {
+  id mock = OCMClassMock([IBGAPM class]);
+  NSString* appFlowName = @"APP_Flow_1";
+
+  [self.instabugBridge endFlow:appFlowName];
+  OCMVerify([mock endFlowWithName:appFlowName]);
+}
+
+- (void) testSetFlowAttribute {
+  id mock = OCMClassMock([IBGAPM class]);
+  NSString* appFlowName = @"APP_Flow_1";
+  NSString* attributeKey = @"Attribute_Key_1";
+  NSString* attributeValue = @"Attribute_Value_1";
+
+  [self.instabugBridge setFlowAttribute:appFlowName :attributeKey :attributeValue];
+  OCMVerify([mock setAttributeForFlowWithName:appFlowName key:attributeKey value:attributeValue]);
+}
+
 - (void) testStartUITrace {
   id mock = OCMClassMock([IBGAPM class]);
   NSString* traceName = @"UITrace_1";
-  
+
   OCMStub([mock startUITraceWithName:traceName]);
   [self.instabugBridge startUITrace:traceName];
   OCMVerify([mock startUITraceWithName:traceName]);
 }
 
 - (void) testEndUITrace {
   id mock = OCMClassMock([IBGAPM class]);
-  
+
   OCMStub([mock endUITrace]);
   [self.instabugBridge endUITrace];
   OCMVerify([mock endUITrace]);

ios/RNInstabug/InstabugAPMBridge.h

@@ -17,10 +17,13 @@
 - (void)setAutoUITraceEnabled:(BOOL)isEnabled;
 - (void)startExecutionTrace:(NSString *)name :(NSString *)id
                            :(RCTPromiseResolveBlock)resolve
-                           :(RCTPromiseRejectBlock)reject;
+                           :(RCTPromiseRejectBlock)reject DEPRECATED_MSG_ATTRIBUTE("Please use APM.startFlow instead.");
 - (void)setExecutionTraceAttribute:(NSString *)id:(NSString *)key
-                                  :(NSString *)value;
-- (void)endExecutionTrace:(NSString *)id;
+                                  :(NSString *)value DEPRECATED_MSG_ATTRIBUTE("Please use APM.setTraceAttribute instead.");
+- (void)endExecutionTrace:(NSString *)id  DEPRECATED_MSG_ATTRIBUTE("Please use APM.endFlow instead.");
+- (void)startFlow:(NSString *)name;
+- (void)endFlow:(NSString *)name;
+- (void)setFlowAttribute:(NSString *)name :(NSString *)key :(NSString *_Nullable)value;
 - (void)startUITrace:(NSString *)name;
 - (void)endUITrace;
 

ios/RNInstabug/InstabugAPMBridge.m

@@ -88,6 +88,19 @@ - (id) init
     }
 }
 
+RCT_EXPORT_METHOD(startFlow: (NSString *)name) {
+    [IBGAPM startFlowWithName:name];
+}
+
+RCT_EXPORT_METHOD(endFlow: (NSString *)name) {
+    [IBGAPM endFlowWithName:name];
+}
+
+
+RCT_EXPORT_METHOD(setFlowAttribute:(NSString *)name :(NSString *)key :(NSString *_Nullable)value) {
+    [IBGAPM setAttributeForFlowWithName:name key:key value:value];
+}
+
 RCT_EXPORT_METHOD(startUITrace:(NSString *)name) {
     [IBGAPM startUITraceWithName:name];
 }

package.json

@@ -60,6 +60,7 @@
     "commander": "^11.0.0",
     "danger": "^11.2.5",
     "eslint": "^8.24.0",
+    "eslint-plugin-jsdoc": "^48.1.0",
     "eslint-plugin-prettier": "^5.0.0",
     "esprima": "^4.0.1",
     "form-data": "^4.0.0",

src/models/Trace.ts

@@ -1,4 +1,5 @@
 import { NativeAPM } from '../native/NativeAPM';
+import type * as APM from '../modules/APM';
 
 export default class Trace {
   constructor(
@@ -8,18 +9,24 @@ export default class Trace {
   ) {}
 
   /**
-   * Add an attribute with key and value to the Trace to be sent.
-   * @param key
-   * @param value
+   * Adds an attribute with a specified key and value to the Trace to be sent.
+   *
+   * @param key - The key of the attribute.
+   * @param value - The value of the attribute.
+   *
+   * @deprecated Please migrate to the App Flows APIs: {@link APM.startFlow}, {@link APM.endFlow}, and {@link APM.setFlowAttribute}.
    */
   setAttribute(key: string, value: string) {
     NativeAPM.setExecutionTraceAttribute(this.id, key, value);
     this.attributes[key] = value;
   }
 
   /**
-   * End Execution Trace
+   * Ends the execution trace.
+   *
+   * @deprecated Please migrate to the App Flows APIs: {@link APM.startFlow}, {@link APM.endFlow}, and {@link APM.setFlowAttribute}.
    */
+
   end() {
     NativeAPM.endExecutionTrace(this.id);
   }