Merge branch 'main' into root-spans-updates

.github/CODEOWNERS

@@ -3,9 +3,9 @@
 scripts @embrace-io/team-devops
 
 # JavaScript
-package*.json @embrace-io/opensource-backend
-**/*.js @embrace-io/opensource-backend
-**/*.ts @embrace-io/opensource-backend
+package*.json @embrace-io/opensource-frontend
+**/*.js @embrace-io/opensource-frontend
+**/*.ts @embrace-io/opensource-frontend
 
 # SDK Teams
 docs/android @embrace-io/opensource-android

docs/ios/changelog.md

@@ -6,6 +6,23 @@ sidebar_position: 4
 
 # iOS/tvOS SDK Changelog
 
+## 6.4.2
+*Oct 2nd, 2024*
+* Fixes
+    * Fixed crash in `URLSessionCaptureService`.
+    * Fixed network body capture logs not being exported.
+    * Fixed logic for background sessions.
+    * Fixed linker error on simulators in iOS 17.5 and below when using cocoapods.
+
+## 6.4.1
+*Sep 26th, 2024*
+* Features
+    * Updated OpenTelemetry dependencies to v1.10.1.
+* Fixes
+    * Fixed logs not having resources from the session when being recovered during the SDK startup.
+    * Fixed crash with the `gtm-session-fetcher` library.
+    * Fixed KSCrash dependency compilation issues in Xcode 16.
+
 ## 6.4.0
 *Sep 13th, 2024*
 * Features

docs/ios/open-source/network-body-capture.md

@@ -0,0 +1,203 @@
+---
+title: Network Body Capture
+description: Embrace can capture network body requests and responses
+sidebar_position: 4
+
+---
+# Network Body Capture
+
+Embrace's SDK uploads basic information about network requests into your sessions to help you understand and troubleshoot networking problems. Embrace can also capture the network body, including the request, response and any headers. 
+
+This feature can only be enabled by your Embrace CS representative, so reach out to them on Slack or create a network body capture request by using the button in the dash. Once configured, your requests will be uploaded to Embrace's servers and delivered to you.
+
+Since this data can be sensitive, the Embrace SDK will encrypt the data before uploading it to our servers. You'll have to provide to your Embrace CS representative a public key that will be used to encrypt the captured data before being stored.
+
+### Generating a Public Key
+
+RSA encryption uses two keys: a private and a public key. You may already be familiar with this protocol and the security team in your organization may already have public keys available for you to use. Before generating new keys, check with your organization.  
+
+There are many ways to generate working key pairs. For these instructions we will use the CLI opensll tool installed by default on most linux-like systems:
+
+```shell-session
+openssl genrsa -out private.pem 2048
+```
+The file you just made should never be shared with anyone outside your organization and should be kept in a safe place. This file is required to decrypt network body data captured by Embrace. Embrace will not have a copy of this. Only you can decrypt the files, and if you lose the private key you also lose the ability to decrypt any data captured by the SDK.
+
+You'll be providing Embrace a public version of the key. This is a derived key that you can safely distribute. Anyone, including Embrace, can use the public key to encrypt data into a form that only your private key can decrypt -- even Embrace cannot read the contents of the encrypted data.
+
+To make the public key run the following command:
+
+```shell-session
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+The file public.pem contains the public key. Use the command `cat public.pem` to view the key. Below is an example we generated while writing this documentation. Remember: it is completely safe to share public keys. Only the private key needs to be protected.
+
+```
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2st+1ouwmsYLOF+kZ/LE
+uZ+jzFuMv+AatKYWXQCwOWP9U02gbXDDOw1rvpeXFUapF1iGF9SASsyBZj4uTfJH
+whalFCZnNasuPbOIKAKtLYCCXyIAjUR6sUAvw+53/tGNPChiMnkYluycwrvd3kyR
+L/Qma6y54sZOiPjNywcmS2Z+IeeJFgJGAtuOgIT9VxwhxGWRIVgH+lmymRvShnLF
+Oj2JGKswFxFaTAjvOWev5mgfg4IbdzFZosy2Llp5JomHWnuAA4D8gh0Fwn7L49tM
+sxX6/KOMRMFzrf0xSfmQH8jsSpE8dAZnUCRDmiFCN63GEoevbGA1rkWIjj65YYXv
+/wIDAQAB
+-----END PUBLIC KEY-----
+```
+
+Above is an example of a valid, public RSA key in text form. Each aspect of that form is important: including the dashes at the beginning and end, and the placement of the return characters after each line. It is important to leave the key in this format and leave the formatting in place.
+
+### OpenTelemetry Format
+
+After the Embrace SDK encrypts the network data, it sends it as an OpenTelemetry log containing the following attributes:
+```
+{
+    "key": "emb.type",
+    "value": "sys.network_capture"
+},
+{
+    "key": "url",
+    "value": "<url_of_the_network_request>"
+},
+{
+    "key": "encryption-mechanism",
+    "value": "hybrid"
+},
+{
+    "key": "payload-algorithm",
+    "value": "aes-256-cbc"
+},
+{
+    "key": "encrypted-payload",
+    "value": "<encrypted_data>"
+},
+{
+    "key": "key-algorithm",
+    "value": "RSA.PKCS1"
+},
+{
+    "key": "encrypted-key",
+    "value": "<encrypted_key>"
+},
+{
+    "key": "aes-iv",
+    "value": "<iv_used_for_decryption>"
+}
+```
+
+You'll need the `encrypted-key`, `aes-iv` and `encrypted-payload` values to decrypt the network data.
+
+### Decryption
+
+The Embrace SDK uses hybrid encryption to secure the data. This means there are actually 2 steps of encryption.
+
+The network data is encrypted using the `aes-256-cbc` algorithm using a randomly generated key. This random key is then encrypted using the public key you provided. In order to decrypt the data, you'll need to decrypt the random key using your private RSA key. After that you'll use this key to decrypt the actual data.
+
+Here's an example script to achieve this:
+
+```
+#!/bin/bash
+
+POSITIONAL_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -in)
+      IN_PATH="$2"
+      shift # past argument
+      shift # past value
+      ;;
+    -out)
+      OUT_PATH="$2"
+      shift # past argument
+      shift # past value
+      ;;
+    -k)
+      KEY_PATH="$2"
+      shift # past argument
+      shift # past value
+      ;;
+    -iv)
+      IV_PATH="$2"
+      shift # past argument
+      shift # past value
+      ;;
+    -pk)
+      PRIVATE_KEY_PATH="$2"
+      shift # past argument
+      shift # past value
+      ;;
+    -h|--help)
+      echo "Usage: $0 -in PATH_TO_ECRYPTED_DATA_FILE -k PATH_TO_ENCRYPTED_KEY_FILE -iv PATH_TO_IV_FILE -pk PATH_TO_PRIVATE_KEY_FILE -out PATH_TO_DECRYPTED_DATA_FILE"
+      echo ""
+      exit 0
+      ;;
+    -*|--*)
+      echo "Unknown option $1"
+      exit 1
+      ;;
+    *)
+      POSITIONAL_ARGS+=("$1") # save positional arg
+      shift # past argument
+      ;;
+  esac
+done
+
+set -- "${POSITIONAL_ARGS[@]}" # restore positional parameters
+
+TMP_PATH="./decryption_tmp"
+rm -rf ${TMP_PATH}
+mkdir ${TMP_PATH}
+
+TMP_DATA_PATH="./decryption_tmp/data.bin"
+TMP_KEY_PATH="./decryption_tmp/key.bin"
+
+# base64 decode payload and key
+openssl base64 -d -A <${IN_PATH} >${TMP_DATA_PATH}
+openssl base64 -d -A <${KEY_PATH} >${TMP_KEY_PATH}
+
+# decrypt symmetric key using private key
+KEY=$(openssl pkeyutl -decrypt -inkey ${PRIVATE_KEY_PATH} -in ${TMP_KEY_PATH})
+
+# read iv file
+IV=$(cat ${IV_PATH})
+
+# # decrypt data
+openssl aes-256-cbc -d -K ${KEY} -iv ${IV} -in ${TMP_DATA_PATH} -out ${OUT_PATH}
+
+# clean up
+rm -rf ${TMP_PATH}
+```
+
+Note that this script expects the `encrypted-key`, `aes-iv` and `encrypted-payload` values to be extracted from the log and placed in individual text files.
+
+Example usage: `sh decrypt.sh -in encrypted_payload.txt -k encrypted_key.txt -iv iv.txt -pk private.pem -out decrypted.txt`
+
+### Payload format
+
+Once decrypted, the payload will be a json containing the following keys:
+
+```
+{
+    url                 // url of the network request (string)
+    http-method         // http method of the network request (string)
+
+    start-time          // start time of the network request in nanoseconds (number)
+    end-time            // end time of the network request in nanoseconds (number)
+
+    matched-url         // the url regex from the body capture rule (string)
+    session-id          // identifier of the active session when the network request was executed (string)
+
+    request-body        // body of the network request (string)
+    request-body-size   // size of the request body (number)
+    request-query       // query from the request (string)    
+    request-headers     // headers of the network request (map)  
+
+    response-body       // body of the network response (string) 
+    response-body-size  // size of the response body (number)
+    response-headers    // headers of the network response (map)   
+    response-status     // status code (number)
+
+    error-message       // error message if the request fails (string)  
+}
+```

docs/react-native/4x/features/current-device-id-api.md

@@ -0,0 +1,32 @@
+---
+title: Current Device ID API
+sidebar_position: 9
+description: Get the Device ID.
+---
+# Current Device ID API
+
+import GetSessionId from '@site/shared/get-session-id.md';
+
+<GetSessionId />
+
+## Integration Steps
+
+In order to use this feature, you will need to follow two steps:
+
+1. Make sure your app is using at least version `4.0.0` of the Embrace SDK.
+2. Implement the API call to obtain the current Device ID.
+
+
+```javascript
+import {getDeviceId} from '@embrace-io/react-native';
+
+const myMethod = () =>{
+    getDeviceId().then(deviceId=>{
+        console.log("Embrace Device Id", deviceId)
+    })
+}
+```  
+
+import CallSupport from '@site/shared/call-support.md';
+
+<CallSupport />

docs/react-native/4x/features/current-session-id-api.md

@@ -0,0 +1,37 @@
+---
+title: Current Session ID API
+sidebar_position: 9
+description: Track the current Embrace session by getting its ID.
+---
+# Current Session ID API
+
+import GetSessionId from '@site/shared/get-session-id.md';
+
+<GetSessionId />
+
+## Integration Steps
+
+In order to use this feature, you will need to follow two steps:
+
+1. Make sure your app is using at least version `3.15.0` of the Embrace SDK.
+2. Implement the API call to obtain the current Session ID.
+3. The method will return a String with the SessionId or null if there is no active session.
+
+
+```javascript
+import {getCurrentSessionId} from '@embrace-io/react-native';
+
+const myMethod = () =>{
+    getCurrentSessionId().then(sessionId=>{
+        console.log("Embrace Session Id", sessionId)
+    })
+}
+```  
+
+:::warning Important
+If you call `getCurrentSessionId()` inside the `AppState change` listener; keep in mind that this is the moment when the session is ending, and a new one is starting. Therefore, there is a high chance that you will get the session ID of the session that is still ending. You might need to delay the call or obtain the session ID at any other point of the app lifecycle to make sure the session ID you get is the one you are looking for.
+:::
+
+import CallSupport from '@site/shared/call-support.md';
+
+<CallSupport />

docs/react-native/4x/features/identify-users.md

@@ -0,0 +1,66 @@
+---
+title: Identify Users
+description: Get to know the users of your React Native application with the Embrace SDK
+sidebar_position: 2
+---
+
+# Know Your Users
+
+Embrace offers two ways you can annotate sessions with information that will help developers and customer service agents find 
+sessions for an unhappy user.
+
+1. [**User Personas**](/react-native/4x/features/identify-users#user-personas). This is data you can set and update about the user of a session.
+1. [**Session Properties**](/react-native/4x/features/identify-users#session-properties). This is data you use to track information about the device or the session itself.
+
+## User Personas
+
+Embrace offers a set of methods to pass information about your users.
+
+```javascript
+import {setUserIdentifier} from '@embrace-io/react-native';
+
+setUserIdentifier('internal_random_id_1234');
+```
+
+The above call annotates the session with a user identifier that you can use later to search for this user.
+For more methods on setting user values, you can see the [source code](/api/react-native/). 
+
+:::warning Important
+Remember that this data will be uploaded to Embrace, so think about the privacy of your users and only include data you are willing to share.
+We recommend using an anonymized or hashed user ID that only your agents can search for.
+:::
+
+You can also set customized values for specific use cases or segments of users.
+
+```javascript
+import {addUserPersona} from '@embrace-io/react-native';
+
+addUserPersona('high_value_cart');
+```
+
+In the above example, the session is annotated with `"high_value_cart"`.
+This will help you identify users who have a certain dollar value in their shopping cart so you can prioritize fixing bugs that affect such users.
+
+## Session Properties
+
+Session Properties are another way to annotate the session.
+The difference between session properties and [user personas](/react-native/4x/features/identify-users#user-personas) is that the former are for items relating to the session or the device and not necessarily to the user.
+However, you are free to use both mechanisms interchangeably.
+
+Here is an example of setting a session property:
+
+```javascript
+import {addSessionProperty} from '@embrace-io/react-native';
+
+addSessionProperty('launch type', 'normal', false);
+```
+
+import PropertyLimit from '@site/shared/property-limit.md';
+
+<PropertyLimit />
+
+In the above, the `'launch type'` property is set with a value of `'normal'`.
+This is to indicate normal launches by the user.
+When the app is launched via a push notification tap, you can set the value `"push"`.
+This can help to understand issues that are hurting push notification adoption rates.
+For example, you could prioritize fixing the issues that affect customers that use push notifications, since they generally provide higher lifetime value.

docs/react-native/4x/features/index.md

@@ -0,0 +1,14 @@
+---
+title: Feature Reference
+description: Learn about the advanced ways Embrace can help your application
+sidebar_position: 2
+---
+
+# React Native Feature Reference
+
+Embrace's SDK includes many advanced features that you can enable to help you understand more about
+how your application is performing in production.
+
+1. [**Know your users.**](/react-native/4x/features/identify-users/) Add your own custom identifiers to users and sessions to make sure you can aggregate and find sessions correctly.
+2. [**Tracking Components.**](/react-native/4x/features/tracking-components/) Track the mounting and unmounting of React Components for your React Native application using the Embrace SDK.
+3. [**Current Session ID API.**](/react-native/4x/features/current-session-id-api.md) This API lets you know what the current Session Id is in case you need to track it separately.