From f1c897828b2e6ead28b5c8effa31ea65a2e98971 Mon Sep 17 00:00:00 2001 From: Misha Marfenko <43787813+PythonHackerr@users.noreply.github.com> Date: Mon, 14 Oct 2024 10:39:36 -0400 Subject: [PATCH 01/10] Added unity sdk documentation page --- docs/sdk/unity.mdx | 9 +++++++++ sidebars.js | 1 + 2 files changed, 10 insertions(+) create mode 100644 docs/sdk/unity.mdx diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx new file mode 100644 index 000000000..6d05fe65d --- /dev/null +++ b/docs/sdk/unity.mdx @@ -0,0 +1,9 @@ +--- +sidebar_label: Unity +title: Unity SDK +sidebar_position: 1 +--- + +## Unity SDK!!! + +Empty for now... diff --git a/sidebars.js b/sidebars.js index 12317ed0e..d8f602fe8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -81,6 +81,7 @@ module.exports = { "sdk/capacitor", "sdk/flutter", "sdk/maui", + "sdk/unity", "sdk/tracking", "sdk/remote-configuration", ], From d2306dc93770044be1a051fdd8bcc794a80acd0b Mon Sep 17 00:00:00 2001 From: Misha Marfenko <43787813+PythonHackerr@users.noreply.github.com> Date: Mon, 14 Oct 2024 10:40:36 -0400 Subject: [PATCH 02/10] added cross-platform compatibility to fix issues on Windows --- package-lock.json | 28 ++++++++++++++++++++++++++++ package.json | 3 ++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/package-lock.json b/package-lock.json index 1f478ecbb..1c8bcb684 100644 --- a/package-lock.json +++ b/package-lock.json @@ -30,6 +30,7 @@ "@types/react": "^17.0.11", "@types/react-helmet": "^6.1.1", "@types/react-router-dom": "^5.1.7", + "cross-env": "^7.0.3", "ejs": "^3.1.6", "husky": "^4.3.8", "lint-staged": "^13.2.3", @@ -5304,6 +5305,24 @@ "node": ">=10" } }, + "node_modules/cross-env": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz", + "integrity": "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw==", + "dev": true, + "dependencies": { + "cross-spawn": "^7.0.1" + }, + "bin": { + "cross-env": "src/bin/cross-env.js", + "cross-env-shell": "src/bin/cross-env-shell.js" + }, + "engines": { + "node": ">=10.14", + "npm": ">=6", + "yarn": ">=1" + } + }, "node_modules/cross-fetch": { "version": "3.1.4", "resolved": "https://registry.npmjs.org/cross-fetch/-/cross-fetch-3.1.4.tgz", @@ -20633,6 +20652,15 @@ "yaml": "^1.10.0" } }, + "cross-env": { + "version": "7.0.3", + "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz", + "integrity": "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw==", + "dev": true, + "requires": { + "cross-spawn": "^7.0.1" + } + }, "cross-fetch": { "version": "3.1.4", "resolved": "https://registry.npmjs.org/cross-fetch/-/cross-fetch-3.1.4.tgz", diff --git a/package.json b/package.json index 034b0ffe0..c8f554cf4 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "private": true, "scripts": { "docusaurus": "docusaurus", - "start": "NODE_OPTIONS=--openssl-legacy-provider docusaurus start", + "start": "cross-env NODE_OPTIONS=--openssl-legacy-provider docusaurus start", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", @@ -49,6 +49,7 @@ "@types/react": "^17.0.11", "@types/react-helmet": "^6.1.1", "@types/react-router-dom": "^5.1.7", + "cross-env": "^7.0.3", "ejs": "^3.1.6", "husky": "^4.3.8", "lint-staged": "^13.2.3", From 65004f11430e43bd55c5c939893503a19ca6e246 Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Thu, 31 Oct 2024 10:08:21 -0400 Subject: [PATCH 03/10] Initial Unity SDK documentation --- docs/sdk/unity.mdx | 301 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 299 insertions(+), 2 deletions(-) diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index 6d05fe65d..671ab2770 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -4,6 +4,303 @@ title: Unity SDK sidebar_position: 1 --- -## Unity SDK!!! +# Unity Wrapper SDK -Empty for now... +This is the documentation for the Unity wrapper module, which provides a thin proxy layer for integrating existing native SDKs offering location tracking and geofencing services. Before integrating, review the native SDK documentation for iOS and Android to understand platform-specific requirements and features. + +The Unity wrapper is developed as a plugin for native SDKs written in Kotlin for Android and Objective-C for iOS. Wrappers for .NET MAUI, React Native, Flutter, and Capacitor are also available. + +See the source on GitHub [here](https://github.com/radarlabs/unity-radar). + +## Supported Unity Versions + +The SDK has been tested on Unity **2022.3.41f**, and **6000.0.24f** versions. However, it should work with Unity versions **2021** and above. + +## Project Structure + +The project directory is organized as follows: + +```plaintext +Assets/ +└── ExternalDependencyManager/ + ├── Editor/ + ... +└── Plugins/ + ├── Android/ + │ ├── sdk-debug.aar + │ └── Dependencies.xml + │ └── gradleTemplate.properties + │ └── mainTemplate.gradle + │ └── settingsTemplate.gradle + ├── iOS/ + │ ├── RadarSDK.xcframework + │ ├── RadarUnityBridge.m +└── Radar/ + └── Demo/ + │ ├── Icons/ + │ ├── Prefabs/ + │ ├── Scenes/ + │ ├── Scripts/ + └── Resources/ + │ ├── Editor/ + │ ├── Settings/ + ├── Scripts/ + │ ├── iOS/ + │ ├── Android/ + │ └── Models/ + │ └── ProxyPlatform/ +``` + + +## Install + +To integrate the Unity wrapper, download or clone the package and include it in your Unity project: + +1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. +2. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. + +### iOS + +1. To install the iOS SDK, navigate to your iOS project directory: + + ```bash + cd ios/ + ``` + +2. In your `Podfile`, ensure that `platform :ios` is set to 10.0 or higher. Then, install the required pods: + + ```bash + pod install + ``` + + You must add location usage descriptions and enable background modes in your `Info.plist` file as described in the [iOS SDK documentation](#). This is essential for accessing location services and geofencing in the background. + +3. To handle location updates effectively, configure background processing options if your app requires tracking location changes when the app is not actively in use. + +:::info + Don't forget to include `RadarSDK.xcframework` under `General > Frameworks, Libraries, and Embedded Content` when building application in XCode. +::: + +### Android + +1. To integrate with the Android SDK, update your app’s `build.gradle` file to include Google Play Services Location. Ensure you are using version `21.0.1` or higher: + + ```gradle + implementation "com.google.android.gms:play-services-location:21.0.1" + ``` + +2. Configure permissions and background processing for location services in your `AndroidManifest.xml`. Add the necessary permissions for foreground and background location access: + + ```xml + + + + ``` + + Refer to the [Android SDK documentation](#) for detailed setup on background tracking and ensuring compliance with Play Store policies regarding location permissions. + +## Integrate + +### Using plugin + +Once installed, access the SDK functionality using RadarSDK namespace: + +```csharp +using RadarSDK; +``` + + + + +### Other APIs + +The Unity SDK exposes following APIs calls: +```bash +initialize, setUserId, getUserId, setMetadata, getLocation, trackVerified, startTrackingVerified, stopTracking, getVerifiedLocationToken, onTokenUpdated +``` +Look at ***RadarExample.cs*** script for example usages + +#### Initialize + +Initialize + +```cs +// Coroutine Call +private void InitializeRadar() +{ + StartCoroutine(RadarSDKManager.Initialize()); +} + +// Async Call +private async Task InitializeRadarAsync() +{ + await RadarSDKManager.InitializeAsync(); +} +``` + +#### SetUserId + +SetUserId +```cs +// Coroutine Call +public void SetUserId(string userId) +{ + RadarSDKManager.SetUserId(userId); +} + +// Async Call +private async Task SetUserIdAsync(string userId) +{ + await RadarSDKManager.SetUserIdAsync(userId); +} +``` + +#### SetMetadata + +SetMetadata +```cs +// Coroutine Call +public void SetMetadata(MetadataContainer metadata) +{ + RadarSDKManager.SetMetadata(metadata); +} + +// Async Call +private async Task SetMetadataAsync(MetadataContainer metadata) +{ + await RadarSDKManager.SetMetadataAsync(metadata); +} +``` + +#### GetLocation + +GetLocation +```cs +// Coroutine Call +public void GetLocation() +{ + StartCoroutine(GetLocationCoroutine()); +} + +// Async Call +private IEnumerator GetLocationCoroutine() +{ + var task = RadarSDKManager.GetLocationAsync(); + + while (!task.IsCompleted) + yield return null; + + if (task.Result != null) + Debug.Log($"Location: Latitude = {task.Result.Value.latitude}, Longitude = {task.Result.Value.longitude}"); + else + Debug.LogError("Failed to retrieve location."); +} +``` + +#### TrackVerified + +TrackVerified +```cs +// Coroutine Call +public void TrackVerified() +{ + StartCoroutine(RadarSDKManager.TrackVerified()); +} + +// Async Call +private async Task TrackVerifiedAsync() +{ + await RadarSDKManager.TrackVerifiedAsync(RadarSDKManager.UserId); +} +``` + +#### StartTrackingVerified + +StartTrackingVerified +```cs +// Coroutine Call +public void StartTrackingVerified() +{ + StartCoroutine(RadarSDKManager.StartTrackingVerified()); +} + +// Async Call +private async Task StartTrackingVerifiedAsync() +{ + await RadarSDKManager.StartTrackingVerifiedAsync(RadarSDKManager.TrackingInterval, RadarSDKManager.UseBeacons); +} +``` + +#### StopTracking + +StopTracking +```cs +// Coroutine Call +public void StopTracking() +{ + StartCoroutine(RadarSDKManager.StopTracking()); +} + +// Async Call +private async Task StopTrackingAsync() +{ + await RadarSDKManager.StopTrackingAsync(); +} +``` + +#### GetVerifiedLocationToken + +Once the native SDK retrieves the location, it sends the data back to Unity. On Android, this is done via RadarJavaProxy, and on iOS, it’s done via a delegate or callback defined in RadarUnityBridge.m +```cs +// Coroutine Call +public void GetVerifiedLocationToken() +{ + StartCoroutine(GetVerifiedLocationTokenCoroutine()); +} + + +private IEnumerator GetVerifiedLocationTokenCoroutine() +{ + var task = RadarSDKManager.GetVerifiedLocationTokenAsync(); + while (!task.IsCompleted) + yield return null; + + if (task.Result.HasValue) + Debug.Log($"Verified Location Token received: Status = {task.Result.Value.Status}"); + else + Debug.LogError("Failed to retrieve verified location token."); +} + +// Async Call +private async Task GetVerifiedLocationTokenAsync() +{ + var result = await RadarSDKManager.GetVerifiedLocationTokenAsync(); + if (result.HasValue) + Debug.Log($"Verified Location Token received: Status = {result.Value.Status}"); + else + Debug.LogError("Failed to retrieve verified location token."); +} +``` + + +#### OnTokenUpdated + +OnTokenUpdated callback +```cs +// Coroutine Call +public void SetVerifiedReceiver() +{ + RadarSDKManager.SetVerifiedReceiver(OnVerifiedLocationTokenReceived); +} + +private void OnVerifiedLocationTokenReceived(RadarVerifiedLocationToken token) +{ + Debug.Log($"Verified location token updated: {token}"); +} +``` + + + +## Support + +Have questions? We're here to help! Contact us at [radar.com/support](https://radar.com/support). From 0a4fdf2cd16a4e7cffa6ccf8e8948e253c43b50e Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Thu, 31 Oct 2024 11:25:18 -0400 Subject: [PATCH 04/10] Initial Unity SDK documentation --- docs/sdk/unity.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index 671ab2770..b17f9093a 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -57,7 +57,8 @@ Assets/ To integrate the Unity wrapper, download or clone the package and include it in your Unity project: 1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. -2. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. +2. Import the ExternalDependencyManager for Unity (EDM4U). You can get it from `Package Manager` or from [repo](https://github.com/googlesamples/unity-jar-resolver): It is required if you want to add and use iOS/Android dependencies directly in your project like: `Android specific libraries (e.g AARs)` or `iOS CocoaPods` +3. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. ### iOS @@ -78,7 +79,7 @@ To integrate the Unity wrapper, download or clone the package and include it in 3. To handle location updates effectively, configure background processing options if your app requires tracking location changes when the app is not actively in use. :::info - Don't forget to include `RadarSDK.xcframework` under `General > Frameworks, Libraries, and Embedded Content` when building application in XCode. + Don't forget to include `RadarSDK.xcframework` under `Your Project General > Frameworks, Libraries, and Embedded Content` when building application in XCode. ::: ### Android @@ -112,7 +113,7 @@ using RadarSDK; -### Other APIs +### Calls to APIs The Unity SDK exposes following APIs calls: ```bash From 1be3339ebcf8fc3350ec1952064fbed36d4c0173 Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Mon, 11 Nov 2024 11:31:06 -0500 Subject: [PATCH 05/10] Updated documentation --- docs/sdk/unity.mdx | 407 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 353 insertions(+), 54 deletions(-) diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index b17f9093a..963e48694 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -4,61 +4,339 @@ title: Unity SDK sidebar_position: 1 --- -# Unity Wrapper SDK +# Unity wrapper SDK -This is the documentation for the Unity wrapper module, which provides a thin proxy layer for integrating existing native SDKs offering location tracking and geofencing services. Before integrating, review the native SDK documentation for iOS and Android to understand platform-specific requirements and features. +This is the documentation for the Unity wrapper/plugin, which provides a thin proxy layer for integrating existing native SDKs offering location tracking and geofencing services. Before integrating, review the native SDK documentation for iOS and Android to understand platform-specific requirements and features. -The Unity wrapper is developed as a plugin for native SDKs written in Kotlin for Android and Objective-C for iOS. Wrappers for .NET MAUI, React Native, Flutter, and Capacitor are also available. +The Unity wrapper is developed as a plugin for native SDKs written in Kotlin for Android and Objective-C for iOS. See the source on GitHub [here](https://github.com/radarlabs/unity-radar). -## Supported Unity Versions +## Supported Unity versions The SDK has been tested on Unity **2022.3.41f**, and **6000.0.24f** versions. However, it should work with Unity versions **2021** and above. -## Project Structure - -The project directory is organized as follows: - -```plaintext -Assets/ -└── ExternalDependencyManager/ - ├── Editor/ - ... -└── Plugins/ - ├── Android/ - │ ├── sdk-debug.aar - │ └── Dependencies.xml - │ └── gradleTemplate.properties - │ └── mainTemplate.gradle - │ └── settingsTemplate.gradle - ├── iOS/ - │ ├── RadarSDK.xcframework - │ ├── RadarUnityBridge.m -└── Radar/ - └── Demo/ - │ ├── Icons/ - │ ├── Prefabs/ - │ ├── Scenes/ - │ ├── Scripts/ - └── Resources/ - │ ├── Editor/ - │ ├── Settings/ - ├── Scripts/ - │ ├── iOS/ - │ ├── Android/ - │ └── Models/ - │ └── ProxyPlatform/ -``` +## Project structure + +
+
+

The project directory is organized as follows:

+
+
+ Demo Scene Status Lights +
+
+ + +### Scripts overview + +This section provides an overview of the main scripts in the Radar SDK for Unity, detailing each script's role and its relationships with other components. This will help you quickly understand how to integrate and utilize the Radar SDK in your Unity project. + +#### 1. `RadarInitializeExample.cs` + +> **Description**: +> Main script used in demo scene. Demonstrates how to initialize and configure the Radar SDK in Unity. This script provides a basic setup and can be used as a starting template for integrating Radar SDK functionality. + +| **Functionality** | **Related Scripts** | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| - Initializes the Radar SDK using `RadarSettingsData`. | - Works with `RadarServiceWrapper` to perform core SDK operations. | +| - Sets up callbacks and configurations required for tracking operations. | - Initializes `RadarErrorHandler` for centralized error handling. | + +#### 2. `RadarServiceWrapper.cs` + +> **Description**: +> Provides a wrapper around the Radar SDK's core functionality, including methods for initializing the SDK, setting the user ID and metadata, and managing tracking operations. It also supports centralized error handling by delegating errors to `RadarErrorHandler`. + +| **Functionality** | **Related Scripts** | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| - Wraps essential SDK methods like initialization, setting user ID, and tracking management. | - Works with `RadarInitializeExample` to initialize and configure SDK. | +| - Exposes an error callback for centralized error management through `RadarErrorHandler`. | - Routes platform-specific SDK calls to `AndroidAdapter` and `iOSAdapter` as needed. | + +#### 3. `Radar.cs` + +> **Description**: +> The main class for interacting with the Radar SDK, `Radar.cs` bridges Unity and the Radar service, handling core setup, user identification, and tracking operations. + +| **Functionality** | **Related Scripts** | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| - Contains methods for initializing the SDK, setting user ID, and managing tracking. | - Called directly by `RadarServiceWrapper` to execute SDK operations. | +| - Routes platform-specific calls to `AndroidAdapter` or `iOSAdapter` based on the platform. | - Delegates platform-specific calls to `AndroidAdapter` and `iOSAdapter`. | + +#### 4. `AndroidAdapter.cs` + +> **Description**: +> Adapter class for Android, bridging Unity and the Radar SDK’s Android `.aar` library. Ensures compatibility with Android-specific integration requirements. + +| **Functionality** | **Related Scripts** | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| - Manages Android-specific calls for initialization, tracking, and stopping tracking. | - Works with `RadarServiceWrapper` and `Radar.cs` to perform Android-specific SDK operations. | +| - Provides platform-specific implementation to support Android features. | - Complements `iOSAdapter` to provide cross-platform support. | + +#### 5. `iOSAdapter.cs` + +> **Description**: +> Adapter class for iOS, bridging Unity and the Radar SDK’s iOS `.xcframework` library. Ensures Radar SDK functionality works seamlessly on iOS devices. + +| **Functionality** | **Related Scripts** | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| - Manages iOS-specific calls for initialization, user ID setup, and tracking. | - Complements `AndroidAdapter` to provide cross-platform support. | +| - Implements `RadarServiceWrapper` and `Radar.cs` methods for iOS. | - Receives method calls from `RadarServiceWrapper` and `Radar.cs` for iOS operations. | + +#### 6. `RadarExample.cs` + +> **Description**: +> Example script showing how to use each method available in the Radar SDK, providing a practical reference for developers integrating Radar into their Unity project. + +| **Functionality** | **Related Scripts** | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| - Demonstrates initializing and configuring the SDK, setting user ID, and using tracking. | - Utilizes `RadarServiceWrapper` for SDK interactions. | +| - Shows error handling via `RadarErrorHandler`. | - Sets up error handling with `RadarErrorHandler` to manage potential errors. | + +### Script Interactions and Flow + +1. **Initialization**: + - `RadarInitializeExample` initializes the SDK by calling `RadarServiceWrapper.Initialize()` and sets up configurations. + - `RadarServiceWrapper` initializes `Radar` and delegates platform-specific initialization to `AndroidAdapter` or `iOSAdapter`. + +2. **Platform-Specific Operations**: + - `RadarServiceWrapper` and `Radar` route SDK calls to `AndroidAdapter` or `iOSAdapter` depending on the platform. + +3. **Error Handling**: + - Errors encountered during SDK usage are sent to `RadarErrorHandler` through a callback set up in `RadarServiceWrapper`. + - `RadarErrorHandler` logs errors and optionally displays messages to the user. + +4. **Example Implementation**: + - `RadarExample` provides a comprehensive example of SDK functions, making it easy for developers to integrate and use the Radar SDK in their projects. + +### Summary + +This architecture enables robust cross-platform support within Unity. With `RadarServiceWrapper` handling core SDK functionality and `AndroidAdapter`/`iOSAdapter` managing platform-specific operations, The example scripts (`RadarInitializeExample` and `RadarExample`) illustrate how to integrate these features, making it easy for developers to get started. + + + + + + + +## Configuring Radar SDK settings in Unity + +The Radar SDK for Unity provides a custom editor window that allows developers to easily configure general settings, keys, and other options necessary for the Radar integration. + +### Accessing the settings + +
+
+

To access the Radar SDK settings, go to `Radar > Settings` in the Unity top menu. This will open the `Radar SDK Settings` window.

+
+
+ Demo Scene Status Lights +
+
+ + +### General settings + +- **User ID**: Unique identifier for the user, required for tracking purposes. Defaults to `DefaultUserId`. If `Add Extension` is enabled, this ID will append platform-specific extensions (e.g., `_WindowsEditor`). + +- **Add Extension**: Toggle to append a platform-specific extension to the User ID. + +- **Enable Debugging**: Toggle this to enable or disable debug logging managed by `LogManager` script. + +### API keys + +- **Test Publishable Key**: Enter your project's test publishable key here. This key is used in development builds `(isDebugBuild = true)`. + +- **Live Publishable Key**: Enter your project's live publishable key here. This key is used in release builds `(isDebugBuild = false)`. + +You can find both publishable keys in your Radar dashboard under the project settings. + +### Tracking and beacons + +- **Tracking Interval (seconds)**: Sets the interval in seconds at which the location tracking updates occur. + +- **Use Beacons**: Toggle to enable or disable the use of beacons in location tracking. + +### Metadata + +- **Metadata**: A container to store or pass additional information required by the application. Click `Edit Metadata` to modify the JSON-formatted data. To add/remove data, modify `MetadataContainer` script. + +### Saving changes + +After configuring the settings, click `Save Settings` to apply your changes. + + ## Install To integrate the Unity wrapper, download or clone the package and include it in your Unity project: -1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. +1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. Ensure it contains all the required files. 2. Import the ExternalDependencyManager for Unity (EDM4U). You can get it from `Package Manager` or from [repo](https://github.com/googlesamples/unity-jar-resolver): It is required if you want to add and use iOS/Android dependencies directly in your project like: `Android specific libraries (e.g AARs)` or `iOS CocoaPods` -3. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. +3. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. + + +## Demo scene + +The Demo Scene in this Unity SDK provides a hands-on way to test each function call with visual feedback and live status updates. The interface is divided into three main sections: [**Top Panel**](#top-panel), [**Left Panel**](#left-panel), and [**Right Panel**](#right-panel). + +### Overview + +
+
+

Each function in the Demo Scene is represented by a button that triggers the respective SDK call. Status lights beside each button give instant feedback on the operation's result:

+
    +
  • Orange: Operation started
    • +
  • Red: Operation failed
    • +
  • Green: Operation succeeded
    • +
+

These status indicators provide quick visual feedback, making it easier to track the state of each function.

+ +

You can also change the publishable key directly in the build. These are some additional operations:

+
    +
  • Save: Saves key in Player Prefs so that the next time it will have a new key
    • +
  • Update: Reinitializes the SDK by calling `RadarServiceWrapper.Initialize()`
    • +
  • Reset: Resets the key to default and reinitializes the SDK
    • +
+

These status indicators provide quick visual feedback, making it easier to track the state of each function.

+
+
+ Demo Scene Status Lights +
+
+ + + + +### Interface layout + +#### Top Panel +The top panel displays key information and status updates for each function call: +- **Status Text**: Shows the current status of the last operation (e.g., `Success`, `Timeout`, or `Failed`). +- **Time Taken**: Displays the time taken for the last operation. +- **User ID Text**: Displays the current User ID. +- **Callback Received Text**: Shows `_onTokenUpdatedText`, indicating that a callback has been received (specific to token updates). +- **Metadata Text**: Displays any metadata set during the session. +- **Location Text**: Displays the last known location. + +#### Left panel +The left panel shows the JSON data retrieved from the latest verified tracking operation. This data is dynamically updated when the `Track Verified` function is called. The process works as follows: + +```csharp +var track = await RadarSDKManager.TrackVerifiedAsync(userId); +if (track != null) +{ + if (track.Value.Status == RadarStatus.SUCCESS) + { + var json = JsonUtility.ToJson(track.Value.Data); + _jsonText.text = JsonFormatter.FormatJson(json, _colors); + SetImageColor(_trackVerifiedImage, _greenColor); // Task completed successfully + } + + _statusText.text = $"Status: {track.Value.Status}"; +} +else +{ + SetImageColor(_trackVerifiedImage, _redColor); // Task failed or timed out + _statusText.text = "Timeout"; +} +``` +#### Right panel + +The right panel contains logs managed by the `LogManager.cs` script. This log section categorizes messages by type: + + +- Log: General operational messages. +- Attention: Important events that may need user attention. +- Warning: Issues that could potentially affect performance or functionality. +- Error: Critical issues that need immediate attention. + +Each log entry shows vital information about the SDK's runtime behavior, making it easier to debug and monitor operations. + +##### Functionality + +The Demo Scene includes the following buttons and their associated functionality: + +- **Set User ID**: Calls `SetUserIdButtonHandler()`. +- **Set Metadata**: Calls `SetMetadata()`. +- **Get Location**: Calls `GetLocation()`. +- **Verify Track**: Calls `TrackVerified()`, verifying location tracking with a status update. +- **Start Tracking**: Calls `StartTrackingVerified()`, initiating background location tracking. +- **Stop Tracking**: Calls `StopTracking()`, stopping background tracking. +- **Get Verified Location Token**: Calls `GetVerifiedLocationToken()`, retrieving a token for verifying location data. + +Each button is connected to its respective function through event listeners: + +```csharp +private IEnumerator Start() +{ + _setUserIdButton.onClick.AddListener(() => { SetUserIdButtonHandler(); }); + _setMetadataButton.onClick.AddListener(() => SetMetadata()); + _getLocationButton.onClick.AddListener(() => GetLocation()); + _verifyTrackButton.onClick.AddListener(() => _ = TrackVerified()); + _startTrackingButton.onClick.AddListener(() => _ = StartTrackingVerified()); + _stopTrackingButton.onClick.AddListener(() => _ = StopTracking()); + _getVerifiedLocationTokenButton.onClick.AddListener(() => _ = GetVerifiedLocationToken()); + // ... +} +``` + + +### Android + + +
+
+

To integrate with the Android SDK, make sure that `Plugins/Android` folder contains following files:

+
    +
  • Dependencies.xml
    • +
  • gradleTemplate.properties
    • +
  • mainTemplate.gradle
    • +
  • sdk-debug.aar
    • +
  • settingsTemplate.gradle
    • +
+

If you are missing files, make sure to include them in the `Player settings` under `Publishing Settings` section:

+
+
+ Demo Scene Status Lights +
+
+ +The content of the files should be as follows: + +`Dependencies.xml`: +```xml + + + + + + + + + + +``` + +`mainTemplate.gradle`: +```gradle +dependencies { + implementation fileTree(dir: 'libs', include: ['*.jar']) + implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" + implementation 'com.google.android.gms:play-services-location:21.0.1' + implementation 'com.google.android.play:integrity:1.2.0' +} +``` + +`gradleTemplate.properties`: +```properties +org.gradle.jvmargs=-Xmx**JVM_HEAP_SIZE**M +org.gradle.parallel=true +unityStreamingAssets=**STREAMING_ASSETS** +android.useAndroidX=true +android.enableJetifier=true +android.suppressUnsupportedCompileSdk=34 +``` ### iOS @@ -79,28 +357,49 @@ To integrate the Unity wrapper, download or clone the package and include it in 3. To handle location updates effectively, configure background processing options if your app requires tracking location changes when the app is not actively in use. :::info - Don't forget to include `RadarSDK.xcframework` under `Your Project General > Frameworks, Libraries, and Embedded Content` when building application in XCode. + Don't forget to include `RadarSDK.xcframework` under `Your Project General > Frameworks, Libraries, and Embedded Content` when building application in Xcode. ::: +****[IMG7]**** -### Android +## Integrate -1. To integrate with the Android SDK, update your app’s `build.gradle` file to include Google Play Services Location. Ensure you are using version `21.0.1` or higher: +### Play Integrity API - ```gradle - implementation "com.google.android.gms:play-services-location:21.0.1" - ``` +To enable the Play Integrity API for Android, visit the Settings page and follow the activation steps. Include the dependency in your app's `build.gradle` file: + +Inside `mainTemplate.gradle`: +```gradle +dependencies { + implementation 'com.google.android.play:integrity:1.2.0' +} +``` -2. Configure permissions and background processing for location services in your `AndroidManifest.xml`. Add the necessary permissions for foreground and background location access: +Inside `Dependencies.xml`: +```xml + + + + + +``` +Use `Radar.trackVerified()` after setup. If you encounter `ERROR_FORBIDDEN`, ensure the device has the latest version of Play Services. For more details, refer to our ****Fraud Documentation****. - ```xml - - - - ``` - Refer to the [Android SDK documentation](#) for detailed setup on background tracking and ensuring compliance with Play Store policies regarding location permissions. +### App attest + +Enable App Attest for iOS via the Settings page by listing valid App IDs. App Attest requires iOS 14 or later and must be added to your Xcode project under Signing & Capabilities. Switch to the production entitlements file for deployment. + +Use `Radar.trackVerified()` after setup. If Radar.trackVerified() returns ERROR_FORBIDDEN, verify iOS compatibility and log details. For in-depth information, see our Fraud Documentation. + +
+
+ Demo Scene Status Lights +
+
+ Demo Scene Status Lights +
+
-## Integrate ### Using plugin From 2757573a2ded6fc8de7ecab87d464681bd0b0ee7 Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Fri, 15 Nov 2024 12:29:22 -0500 Subject: [PATCH 06/10] updated documentation --- An | 0 docs/sdk/unity.mdx | 137 ++++++------------ ...ption\357\200\252\357\200\252\357\200\272" | 0 3 files changed, 45 insertions(+), 92 deletions(-) create mode 100644 An create mode 100644 "\357\200\252\357\200\252Description\357\200\252\357\200\252\357\200\272" diff --git a/An b/An new file mode 100644 index 000000000..e69de29bb diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index 963e48694..03496c6f0 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -32,7 +32,7 @@ The SDK has been tested on Unity **2022.3.41f**, and **6000.0.24f** versions. Ho This section provides an overview of the main scripts in the Radar SDK for Unity, detailing each script's role and its relationships with other components. This will help you quickly understand how to integrate and utilize the Radar SDK in your Unity project. -#### 1. `RadarInitializeExample.cs` +#### 1. `RadarExample.cs` > **Description**: > Main script used in demo scene. Demonstrates how to initialize and configure the Radar SDK in Unity. This script provides a basic setup and can be used as a starting template for integrating Radar SDK functionality. @@ -49,7 +49,7 @@ This section provides an overview of the main scripts in the Radar SDK for Unity | **Functionality** | **Related Scripts** | |------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Wraps essential SDK methods like initialization, setting user ID, and tracking management. | - Works with `RadarInitializeExample` to initialize and configure SDK. | +| - Wraps essential SDK methods like initialization, setting user ID, and tracking management. | - Works with `RadarExample` to initialize and configure SDK. | | - Exposes an error callback for centralized error management through `RadarErrorHandler`. | - Routes platform-specific SDK calls to `AndroidAdapter` and `iOSAdapter` as needed. | #### 3. `Radar.cs` @@ -82,7 +82,7 @@ This section provides an overview of the main scripts in the Radar SDK for Unity | - Manages iOS-specific calls for initialization, user ID setup, and tracking. | - Complements `AndroidAdapter` to provide cross-platform support. | | - Implements `RadarServiceWrapper` and `Radar.cs` methods for iOS. | - Receives method calls from `RadarServiceWrapper` and `Radar.cs` for iOS operations. | -#### 6. `RadarExample.cs` +#### 6. `RadarUsageExample.cs` > **Description**: > Example script showing how to use each method available in the Radar SDK, providing a practical reference for developers integrating Radar into their Unity project. @@ -95,7 +95,7 @@ This section provides an overview of the main scripts in the Radar SDK for Unity ### Script Interactions and Flow 1. **Initialization**: - - `RadarInitializeExample` initializes the SDK by calling `RadarServiceWrapper.Initialize()` and sets up configurations. + - `RadarExample` initializes the SDK by calling `RadarServiceWrapper.Initialize()` and sets up configurations. - `RadarServiceWrapper` initializes `Radar` and delegates platform-specific initialization to `AndroidAdapter` or `iOSAdapter`. 2. **Platform-Specific Operations**: @@ -106,11 +106,11 @@ This section provides an overview of the main scripts in the Radar SDK for Unity - `RadarErrorHandler` logs errors and optionally displays messages to the user. 4. **Example Implementation**: - - `RadarExample` provides a comprehensive example of SDK functions, making it easy for developers to integrate and use the Radar SDK in their projects. + - `RadarUsageExample` provides a comprehensive example of SDK functions, making it easy for developers to integrate and use the Radar SDK in their projects. ### Summary -This architecture enables robust cross-platform support within Unity. With `RadarServiceWrapper` handling core SDK functionality and `AndroidAdapter`/`iOSAdapter` managing platform-specific operations, The example scripts (`RadarInitializeExample` and `RadarExample`) illustrate how to integrate these features, making it easy for developers to get started. +This architecture enables robust cross-platform support within Unity. With `RadarServiceWrapper` handling core SDK functionality and `AndroidAdapter`/`iOSAdapter` managing platform-specific operations, The example scripts (`RadarExample` and `RadarUsageExample`) illustrate how to integrate these features, making it easy for developers to get started. @@ -418,23 +418,17 @@ The Unity SDK exposes following APIs calls: ```bash initialize, setUserId, getUserId, setMetadata, getLocation, trackVerified, startTrackingVerified, stopTracking, getVerifiedLocationToken, onTokenUpdated ``` -Look at ***RadarExample.cs*** script for example usages +Look at ***RadarUsageExample.cs*** script for example usages #### Initialize Initialize ```cs -// Coroutine Call private void InitializeRadar() { - StartCoroutine(RadarSDKManager.Initialize()); -} - -// Async Call -private async Task InitializeRadarAsync() -{ - await RadarSDKManager.InitializeAsync(); + string publishableKey = Debug.isDebugBuild ? RadarSDKManager.TestPublishableKey : RadarSDKManager.LivePublishableKey; + Radar.Initialize(publishableKey, fraud: true); } ``` @@ -442,16 +436,9 @@ private async Task InitializeRadarAsync() SetUserId ```cs -// Coroutine Call -public void SetUserId(string userId) +private void SetUserId(string userId) { - RadarSDKManager.SetUserId(userId); -} - -// Async Call -private async Task SetUserIdAsync(string userId) -{ - await RadarSDKManager.SetUserIdAsync(userId); + Radar.SetUserId(userId); } ``` @@ -459,16 +446,9 @@ private async Task SetUserIdAsync(string userId) SetMetadata ```cs -// Coroutine Call -public void SetMetadata(MetadataContainer metadata) +private void SetMetadata(MetadataContainer metadata) { - RadarSDKManager.SetMetadata(metadata); -} - -// Async Call -private async Task SetMetadataAsync(MetadataContainer metadata) -{ - await RadarSDKManager.SetMetadataAsync(metadata); + Radar.SetMetadata(metadata); } ``` @@ -476,24 +456,23 @@ private async Task SetMetadataAsync(MetadataContainer metadata) GetLocation ```cs -// Coroutine Call -public void GetLocation() -{ - StartCoroutine(GetLocationCoroutine()); -} - -// Async Call -private IEnumerator GetLocationCoroutine() +private Task GetLocation() { - var task = RadarSDKManager.GetLocationAsync(); - - while (!task.IsCompleted) - yield return null; - - if (task.Result != null) - Debug.Log($"Location: Latitude = {task.Result.Value.latitude}, Longitude = {task.Result.Value.longitude}"); - else - Debug.LogError("Failed to retrieve location."); + var tcs = new TaskCompletionSource(); + + Radar.GetLocation(location => + { + if (location.coordinates != null) + { + LogManager.Instance.Log($"Location received: Latitude = {location.latitude}, Longitude = {location.longitude}", LogType.Warning); + } + else + { + LogManager.Instance.Log("Failed to get location", LogType.Error); + } + }); + + return tcs.Task; } ``` @@ -501,16 +480,9 @@ private IEnumerator GetLocationCoroutine() TrackVerified ```cs -// Coroutine Call -public void TrackVerified() -{ - StartCoroutine(RadarSDKManager.TrackVerified()); -} - -// Async Call private async Task TrackVerifiedAsync() { - await RadarSDKManager.TrackVerifiedAsync(RadarSDKManager.UserId); + await Radar.TrackVerified(); } ``` @@ -518,16 +490,9 @@ private async Task TrackVerifiedAsync() StartTrackingVerified ```cs -// Coroutine Call -public void StartTrackingVerified() -{ - StartCoroutine(RadarSDKManager.StartTrackingVerified()); -} - -// Async Call private async Task StartTrackingVerifiedAsync() { - await RadarSDKManager.StartTrackingVerifiedAsync(RadarSDKManager.TrackingInterval, RadarSDKManager.UseBeacons); + await Radar.StartTrackingVerified(RadarSDKManager.TrackingInterval, RadarSDKManager.UseBeacons); } ``` @@ -535,16 +500,9 @@ private async Task StartTrackingVerifiedAsync() StopTracking ```cs -// Coroutine Call -public void StopTracking() -{ - StartCoroutine(RadarSDKManager.StopTracking()); -} - -// Async Call private async Task StopTrackingAsync() { - await RadarSDKManager.StopTrackingAsync(); + await Radar.StopTracking(); } ``` @@ -552,33 +510,28 @@ private async Task StopTrackingAsync() Once the native SDK retrieves the location, it sends the data back to Unity. On Android, this is done via RadarJavaProxy, and on iOS, it’s done via a delegate or callback defined in RadarUnityBridge.m ```cs -// Coroutine Call -public void GetVerifiedLocationToken() +private void GetVerifiedLocationToken() { StartCoroutine(GetVerifiedLocationTokenCoroutine()); } - private IEnumerator GetVerifiedLocationTokenCoroutine() { - var task = RadarSDKManager.GetVerifiedLocationTokenAsync(); + var task = Radar.GetVerifiedLocationToken(); + while (!task.IsCompleted) + { yield return null; + } - if (task.Result.HasValue) - Debug.Log($"Verified Location Token received: Status = {task.Result.Value.Status}"); - else - Debug.LogError("Failed to retrieve verified location token."); -} - -// Async Call -private async Task GetVerifiedLocationTokenAsync() -{ - var result = await RadarSDKManager.GetVerifiedLocationTokenAsync(); - if (result.HasValue) - Debug.Log($"Verified Location Token received: Status = {result.Value.Status}"); + if (task.IsCompleted && task.Result.Data != null) + { + Debug.Log($"Verified Location Token received: Status = {task.Result.Status}"); + } else + { Debug.LogError("Failed to retrieve verified location token."); + } } ``` @@ -588,9 +541,9 @@ private async Task GetVerifiedLocationTokenAsync() OnTokenUpdated callback ```cs // Coroutine Call -public void SetVerifiedReceiver() +private void SetVerifiedReceiver() { - RadarSDKManager.SetVerifiedReceiver(OnVerifiedLocationTokenReceived); + Radar.SetVerifiedReceiver(OnVerifiedLocationTokenReceived); } private void OnVerifiedLocationTokenReceived(RadarVerifiedLocationToken token) diff --git "a/\357\200\252\357\200\252Description\357\200\252\357\200\252\357\200\272" "b/\357\200\252\357\200\252Description\357\200\252\357\200\252\357\200\272" new file mode 100644 index 000000000..e69de29bb From 80ae82d5d4e190cdcd07c1d37401bfa13efdd097 Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Fri, 15 Nov 2024 12:35:27 -0500 Subject: [PATCH 07/10] updated documentation --- docs/sdk/unity.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index 03496c6f0..b38afb8f6 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -129,7 +129,7 @@ The Radar SDK for Unity provides a custom editor window that allows developers t

To access the Radar SDK settings, go to `Radar > Settings` in the Unity top menu. This will open the `Radar SDK Settings` window.

- Demo Scene Status Lights + Demo Scene Status Lights
@@ -359,7 +359,12 @@ android.suppressUnsupportedCompileSdk=34 :::info Don't forget to include `RadarSDK.xcframework` under `Your Project General > Frameworks, Libraries, and Embedded Content` when building application in Xcode. ::: -****[IMG7]**** + + +
+ Demo Scene Status Lights +
+ ## Integrate @@ -540,7 +545,6 @@ private IEnumerator GetVerifiedLocationTokenCoroutine() OnTokenUpdated callback ```cs -// Coroutine Call private void SetVerifiedReceiver() { Radar.SetVerifiedReceiver(OnVerifiedLocationTokenReceived); From f892cd2351b360aeb69956383d676b9bb24b8b3e Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Fri, 6 Dec 2024 09:07:00 -0500 Subject: [PATCH 08/10] Revised documentation --- docs/sdk/unity.mdx | 363 ++++++++++----------------------------------- 1 file changed, 79 insertions(+), 284 deletions(-) diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index b38afb8f6..9101bc2cd 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -8,279 +8,67 @@ sidebar_position: 1 This is the documentation for the Unity wrapper/plugin, which provides a thin proxy layer for integrating existing native SDKs offering location tracking and geofencing services. Before integrating, review the native SDK documentation for iOS and Android to understand platform-specific requirements and features. -The Unity wrapper is developed as a plugin for native SDKs written in Kotlin for Android and Objective-C for iOS. - See the source on GitHub [here](https://github.com/radarlabs/unity-radar). -## Supported Unity versions - -The SDK has been tested on Unity **2022.3.41f**, and **6000.0.24f** versions. However, it should work with Unity versions **2021** and above. - -## Project structure - -
-
-

The project directory is organized as follows:

-
-
- Demo Scene Status Lights -
-
- - -### Scripts overview - -This section provides an overview of the main scripts in the Radar SDK for Unity, detailing each script's role and its relationships with other components. This will help you quickly understand how to integrate and utilize the Radar SDK in your Unity project. - -#### 1. `RadarExample.cs` - -> **Description**: -> Main script used in demo scene. Demonstrates how to initialize and configure the Radar SDK in Unity. This script provides a basic setup and can be used as a starting template for integrating Radar SDK functionality. - -| **Functionality** | **Related Scripts** | -|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Initializes the Radar SDK using `RadarSettingsData`. | - Works with `RadarServiceWrapper` to perform core SDK operations. | -| - Sets up callbacks and configurations required for tracking operations. | - Initializes `RadarErrorHandler` for centralized error handling. | - -#### 2. `RadarServiceWrapper.cs` - -> **Description**: -> Provides a wrapper around the Radar SDK's core functionality, including methods for initializing the SDK, setting the user ID and metadata, and managing tracking operations. It also supports centralized error handling by delegating errors to `RadarErrorHandler`. - -| **Functionality** | **Related Scripts** | -|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Wraps essential SDK methods like initialization, setting user ID, and tracking management. | - Works with `RadarExample` to initialize and configure SDK. | -| - Exposes an error callback for centralized error management through `RadarErrorHandler`. | - Routes platform-specific SDK calls to `AndroidAdapter` and `iOSAdapter` as needed. | - -#### 3. `Radar.cs` - -> **Description**: -> The main class for interacting with the Radar SDK, `Radar.cs` bridges Unity and the Radar service, handling core setup, user identification, and tracking operations. - -| **Functionality** | **Related Scripts** | -|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Contains methods for initializing the SDK, setting user ID, and managing tracking. | - Called directly by `RadarServiceWrapper` to execute SDK operations. | -| - Routes platform-specific calls to `AndroidAdapter` or `iOSAdapter` based on the platform. | - Delegates platform-specific calls to `AndroidAdapter` and `iOSAdapter`. | - -#### 4. `AndroidAdapter.cs` - -> **Description**: -> Adapter class for Android, bridging Unity and the Radar SDK’s Android `.aar` library. Ensures compatibility with Android-specific integration requirements. - -| **Functionality** | **Related Scripts** | -|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Manages Android-specific calls for initialization, tracking, and stopping tracking. | - Works with `RadarServiceWrapper` and `Radar.cs` to perform Android-specific SDK operations. | -| - Provides platform-specific implementation to support Android features. | - Complements `iOSAdapter` to provide cross-platform support. | - -#### 5. `iOSAdapter.cs` - -> **Description**: -> Adapter class for iOS, bridging Unity and the Radar SDK’s iOS `.xcframework` library. Ensures Radar SDK functionality works seamlessly on iOS devices. - -| **Functionality** | **Related Scripts** | -|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Manages iOS-specific calls for initialization, user ID setup, and tracking. | - Complements `AndroidAdapter` to provide cross-platform support. | -| - Implements `RadarServiceWrapper` and `Radar.cs` methods for iOS. | - Receives method calls from `RadarServiceWrapper` and `Radar.cs` for iOS operations. | - -#### 6. `RadarUsageExample.cs` - -> **Description**: -> Example script showing how to use each method available in the Radar SDK, providing a practical reference for developers integrating Radar into their Unity project. - -| **Functionality** | **Related Scripts** | -|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| -| - Demonstrates initializing and configuring the SDK, setting user ID, and using tracking. | - Utilizes `RadarServiceWrapper` for SDK interactions. | -| - Shows error handling via `RadarErrorHandler`. | - Sets up error handling with `RadarErrorHandler` to manage potential errors. | - -### Script Interactions and Flow - -1. **Initialization**: - - `RadarExample` initializes the SDK by calling `RadarServiceWrapper.Initialize()` and sets up configurations. - - `RadarServiceWrapper` initializes `Radar` and delegates platform-specific initialization to `AndroidAdapter` or `iOSAdapter`. - -2. **Platform-Specific Operations**: - - `RadarServiceWrapper` and `Radar` route SDK calls to `AndroidAdapter` or `iOSAdapter` depending on the platform. - -3. **Error Handling**: - - Errors encountered during SDK usage are sent to `RadarErrorHandler` through a callback set up in `RadarServiceWrapper`. - - `RadarErrorHandler` logs errors and optionally displays messages to the user. - -4. **Example Implementation**: - - `RadarUsageExample` provides a comprehensive example of SDK functions, making it easy for developers to integrate and use the Radar SDK in their projects. - -### Summary - -This architecture enables robust cross-platform support within Unity. With `RadarServiceWrapper` handling core SDK functionality and `AndroidAdapter`/`iOSAdapter` managing platform-specific operations, The example scripts (`RadarExample` and `RadarUsageExample`) illustrate how to integrate these features, making it easy for developers to get started. - - - - - - - -## Configuring Radar SDK settings in Unity - -The Radar SDK for Unity provides a custom editor window that allows developers to easily configure general settings, keys, and other options necessary for the Radar integration. - -### Accessing the settings - -
-
-

To access the Radar SDK settings, go to `Radar > Settings` in the Unity top menu. This will open the `Radar SDK Settings` window.

-
-
- Demo Scene Status Lights -
-
- - -### General settings - -- **User ID**: Unique identifier for the user, required for tracking purposes. Defaults to `DefaultUserId`. If `Add Extension` is enabled, this ID will append platform-specific extensions (e.g., `_WindowsEditor`). - -- **Add Extension**: Toggle to append a platform-specific extension to the User ID. - -- **Enable Debugging**: Toggle this to enable or disable debug logging managed by `LogManager` script. - -### API keys - -- **Test Publishable Key**: Enter your project's test publishable key here. This key is used in development builds `(isDebugBuild = true)`. - -- **Live Publishable Key**: Enter your project's live publishable key here. This key is used in release builds `(isDebugBuild = false)`. - -You can find both publishable keys in your Radar dashboard under the project settings. - -### Tracking and beacons - -- **Tracking Interval (seconds)**: Sets the interval in seconds at which the location tracking updates occur. - -- **Use Beacons**: Toggle to enable or disable the use of beacons in location tracking. - -### Metadata - -- **Metadata**: A container to store or pass additional information required by the application. Click `Edit Metadata` to modify the JSON-formatted data. To add/remove data, modify `MetadataContainer` script. - -### Saving changes - -After configuring the settings, click `Save Settings` to apply your changes. - - - +Scripts documentation and Demo scene overview can be found in project READMEs. ## Install -To integrate the Unity wrapper, download or clone the package and include it in your Unity project: +To integrate the Unity SDK, download or clone the package and include it in your Unity project: 1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. Ensure it contains all the required files. -2. Import the ExternalDependencyManager for Unity (EDM4U). You can get it from `Package Manager` or from [repo](https://github.com/googlesamples/unity-jar-resolver): It is required if you want to add and use iOS/Android dependencies directly in your project like: `Android specific libraries (e.g AARs)` or `iOS CocoaPods` +2. Import the ExternalDependencyManager for Unity (EDM4U). It is included in the project but you can get it from `Package Manager` or from [repo](https://github.com/googlesamples/unity-jar-resolver): It is required if you want to add and use iOS/Android dependencies directly in your project like: `Android specific libraries (e.g AARs)` or `iOS CocoaPods` 3. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. -## Demo scene - -The Demo Scene in this Unity SDK provides a hands-on way to test each function call with visual feedback and live status updates. The interface is divided into three main sections: [**Top Panel**](#top-panel), [**Left Panel**](#left-panel), and [**Right Panel**](#right-panel). - -### Overview - -
-
-

Each function in the Demo Scene is represented by a button that triggers the respective SDK call. Status lights beside each button give instant feedback on the operation's result:

-
    -
  • Orange: Operation started
    • -
  • Red: Operation failed
    • -
  • Green: Operation succeeded
    • -
-

These status indicators provide quick visual feedback, making it easier to track the state of each function.

- -

You can also change the publishable key directly in the build. These are some additional operations:

-
    -
  • Save: Saves key in Player Prefs so that the next time it will have a new key
    • -
  • Update: Reinitializes the SDK by calling `RadarServiceWrapper.Initialize()`
    • -
  • Reset: Resets the key to default and reinitializes the SDK
    • -
-

These status indicators provide quick visual feedback, making it easier to track the state of each function.

-
-
- Demo Scene Status Lights -
-
- - +### Supported Unity versions +The SDK has been tested on Unity **2022.3.41f**, and **6000.0.24f** versions. However, it should work with Unity versions **2021** and above. -### Interface layout -#### Top Panel -The top panel displays key information and status updates for each function call: -- **Status Text**: Shows the current status of the last operation (e.g., `Success`, `Timeout`, or `Failed`). -- **Time Taken**: Displays the time taken for the last operation. -- **User ID Text**: Displays the current User ID. -- **Callback Received Text**: Shows `_onTokenUpdatedText`, indicating that a callback has been received (specific to token updates). -- **Metadata Text**: Displays any metadata set during the session. -- **Location Text**: Displays the last known location. +## Integrate -#### Left panel -The left panel shows the JSON data retrieved from the latest verified tracking operation. This data is dynamically updated when the `Track Verified` function is called. The process works as follows: +### Play Integrity API +To enable the Play Integrity API for Android, enable the [Play Integrity API](https://developer.android.com/google/play/integrity) on the [Settings page](https://radar.com/dashboard/settings) and follow the activation steps. Include the dependency in your app's `build.gradle` file: -```csharp -var track = await RadarSDKManager.TrackVerifiedAsync(userId); -if (track != null) -{ - if (track.Value.Status == RadarStatus.SUCCESS) - { - var json = JsonUtility.ToJson(track.Value.Data); - _jsonText.text = JsonFormatter.FormatJson(json, _colors); - SetImageColor(_trackVerifiedImage, _greenColor); // Task completed successfully - } - - _statusText.text = $"Status: {track.Value.Status}"; -} -else -{ - SetImageColor(_trackVerifiedImage, _redColor); // Task failed or timed out - _statusText.text = "Timeout"; +Inside `mainTemplate.gradle`: +```gradle +dependencies { + implementation 'com.google.android.play:integrity:1.2.0' } ``` -#### Right panel -The right panel contains logs managed by the `LogManager.cs` script. This log section categorizes messages by type: +Inside `Dependencies.xml`: +```xml + + + + + +``` + +Use `Radar.trackVerified()` after setup. If you encounter `ERROR_FORBIDDEN`, ensure the device has the latest version of Play Services. For more details, refer to our [Fraud Documentation](https://radar.com/documentation/fraud). -- Log: General operational messages. -- Attention: Important events that may need user attention. -- Warning: Issues that could potentially affect performance or functionality. -- Error: Critical issues that need immediate attention. +### App attest -Each log entry shows vital information about the SDK's runtime behavior, making it easier to debug and monitor operations. +Enable App Attest for iOS via the Settings page by listing valid App IDs. App Attest requires iOS 14 or later and must be added to your Xcode project under Signing & Capabilities. Switch to the production entitlements file for deployment. -##### Functionality +Use `Radar.trackVerified()` after setup. If Radar.trackVerified() returns ERROR_FORBIDDEN, verify iOS compatibility and log details. For in-depth information, see our [Fraud Documentation](https://radar.com/documentation/fraud). -The Demo Scene includes the following buttons and their associated functionality: +
+
+ Demo Scene Status Lights +
+
+ Demo Scene Status Lights +
+
-- **Set User ID**: Calls `SetUserIdButtonHandler()`. -- **Set Metadata**: Calls `SetMetadata()`. -- **Get Location**: Calls `GetLocation()`. -- **Verify Track**: Calls `TrackVerified()`, verifying location tracking with a status update. -- **Start Tracking**: Calls `StartTrackingVerified()`, initiating background location tracking. -- **Stop Tracking**: Calls `StopTracking()`, stopping background tracking. -- **Get Verified Location Token**: Calls `GetVerifiedLocationToken()`, retrieving a token for verifying location data. -Each button is connected to its respective function through event listeners: -```csharp -private IEnumerator Start() -{ - _setUserIdButton.onClick.AddListener(() => { SetUserIdButtonHandler(); }); - _setMetadataButton.onClick.AddListener(() => SetMetadata()); - _getLocationButton.onClick.AddListener(() => GetLocation()); - _verifyTrackButton.onClick.AddListener(() => _ = TrackVerified()); - _startTrackingButton.onClick.AddListener(() => _ = StartTrackingVerified()); - _stopTrackingButton.onClick.AddListener(() => _ = StopTracking()); - _getVerifiedLocationTokenButton.onClick.AddListener(() => _ = GetVerifiedLocationToken()); - // ... -} -``` +## Platform-specific configuration ### Android @@ -366,47 +154,58 @@ android.suppressUnsupportedCompileSdk=34 -## Integrate -### Play Integrity API +## Configuring Radar SDK settings in Unity -To enable the Play Integrity API for Android, visit the Settings page and follow the activation steps. Include the dependency in your app's `build.gradle` file: +The Radar SDK for Unity provides a custom editor window that allows developers to easily configure general settings, keys, and other options necessary for the Radar integration. -Inside `mainTemplate.gradle`: -```gradle -dependencies { - implementation 'com.google.android.play:integrity:1.2.0' -} -``` +### Accessing the settings -Inside `Dependencies.xml`: -```xml - - - - - -``` -Use `Radar.trackVerified()` after setup. If you encounter `ERROR_FORBIDDEN`, ensure the device has the latest version of Play Services. For more details, refer to our ****Fraud Documentation****. +
+
+

To access the Radar SDK settings, go to `Radar > Settings` in the Unity top menu. This will open the `Radar SDK Settings` window.

+
+
+ Demo Scene Status Lights +
+
-### App attest +#### General settings -Enable App Attest for iOS via the Settings page by listing valid App IDs. App Attest requires iOS 14 or later and must be added to your Xcode project under Signing & Capabilities. Switch to the production entitlements file for deployment. +- **User ID**: Unique identifier for the user, required for tracking purposes. Defaults to `DefaultUserId`. If `Add Extension` is enabled, this ID will append platform-specific extensions (e.g., `_WindowsEditor`). + +- **Add Extension**: Toggle to append a platform-specific extension to the User ID. + +- **Enable Debugging**: Toggle this to enable or disable debug logging managed by `LogManager` script. + +#### API keys + +- **Test Publishable Key**: Enter your project's test publishable key here. This key is used in development builds `(isDebugBuild = true)`. + +- **Live Publishable Key**: Enter your project's live publishable key here. This key is used in release builds `(isDebugBuild = false)`. + +You can find both publishable keys in your Radar dashboard under the project settings. + +#### Tracking and beacons + +- **Tracking Interval (seconds)**: Sets the interval in seconds at which the location tracking updates occur. + +- **Use Beacons**: Toggle to enable or disable the use of beacons in location tracking. + +#### Metadata + +- **Metadata**: A container to store or pass additional information required by the application. Click `Edit Metadata` to modify the JSON-formatted data. To add/remove data, modify `MetadataContainer` script. + +#### Saving changes + +After configuring the settings, click `Save Settings` to apply your changes. -Use `Radar.trackVerified()` after setup. If Radar.trackVerified() returns ERROR_FORBIDDEN, verify iOS compatibility and log details. For in-depth information, see our Fraud Documentation. -
-
- Demo Scene Status Lights -
-
- Demo Scene Status Lights -
-
-### Using plugin + +## Using plugin Once installed, access the SDK functionality using RadarSDK namespace: @@ -417,6 +216,7 @@ using RadarSDK; + ### Calls to APIs The Unity SDK exposes following APIs calls: @@ -427,8 +227,6 @@ Look at ***RadarUsageExample.cs*** script for example usages #### Initialize -Initialize - ```cs private void InitializeRadar() { @@ -439,7 +237,6 @@ private void InitializeRadar() #### SetUserId -SetUserId ```cs private void SetUserId(string userId) { @@ -449,7 +246,6 @@ private void SetUserId(string userId) #### SetMetadata -SetMetadata ```cs private void SetMetadata(MetadataContainer metadata) { @@ -459,7 +255,6 @@ private void SetMetadata(MetadataContainer metadata) #### GetLocation -GetLocation ```cs private Task GetLocation() { @@ -483,7 +278,6 @@ private Task GetLocation() #### TrackVerified -TrackVerified ```cs private async Task TrackVerifiedAsync() { @@ -493,7 +287,6 @@ private async Task TrackVerifiedAsync() #### StartTrackingVerified -StartTrackingVerified ```cs private async Task StartTrackingVerifiedAsync() { @@ -503,7 +296,6 @@ private async Task StartTrackingVerifiedAsync() #### StopTracking -StopTracking ```cs private async Task StopTrackingAsync() { @@ -556,7 +348,10 @@ private void OnVerifiedLocationTokenReceived(RadarVerifiedLocationToken token) } ``` +## Error handling +### Troubleshooting +on the way... ## Support From b2bcdd53fea32a251c98f0b4e4200717a79ccef0 Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Mon, 9 Dec 2024 11:02:03 -0500 Subject: [PATCH 09/10] Revised documentation --- docs/sdk/unity.mdx | 56 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 53 insertions(+), 3 deletions(-) diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index 9101bc2cd..c44b95a0b 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -350,9 +350,59 @@ private void OnVerifiedLocationTokenReceived(RadarVerifiedLocationToken token) ## Error handling -### Troubleshooting -on the way... +The Radar SDK includes built-in error handling to ensure that errors are logged and troubleshooting is streamlined. Below is an overview of how to manage and handle errors effectively using the SDK. + +### Setting Up Error Handling + +The SDK initializes a centralized error management system to capture and log errors globally. The `RadarErrorHandler` class is responsible for setting up error callbacks and routing error messages to the `LogManager` for visual logging. + +#### Steps to Enable Error Handling + +1. **Initialize Error Handling**: + Call `RadarErrorHandler.InitializeErrorHandling()` during the application's startup to activate global error monitoring. + + ```cs + RadarErrorHandler.InitializeErrorHandling(); + ``` + +2. **Error Logging**: + All errors caught by the SDK will be logged and displayed in the `LogManager`'s UI text box. The log is thread-safe and formatted with color coding: + - **Red** - `LogType.Error` for critical errors. + - **Yellow** - `LogType.Warning` for warnings. + - **Orange** - `LogType.Attention` for attention-level messages. + - **White** - `LogType.Log` for standard logs. + +The `LogManager` provides visual feedback for debugging. + +Use the `LogManager.SetLogConsole(true/false)` to enable or disable console logging. +Use the `ClearConsole` method to reset the visual log for clarity. + + +#### Common Issues and Solutions +Refer to the Radar documentation for error-specific troubleshooting, such as: +- **`ERROR_PERMISSIONS`**: Ensure location permissions are granted. +- **`ERROR_NETWORK`**: Verify internet connectivity. +- **`fraud.proxy == true`**: Ask users to disconnect from VPNs or proxy servers. + +See the [Fraud Error Handling Documentation](https://radar.com/documentation/fraud#error-handling) for detailed error messages and resolutions. + +### Example Integration + +Here’s an example of how to log errors using the SDK: + +```csharp +try +{ + Radar.SomeFunctionality(); +} +catch (Exception ex) +{ + LogManager.Instance.Log($"Unhandled Exception: {ex.Message}", LogType.Error); +} +``` + + ## Support -Have questions? We're here to help! Contact us at [radar.com/support](https://radar.com/support). +Have questions? We're here to help! Contact us at [radar.com/support](https://radar.com/support). \ No newline at end of file From 5fdb6f4eeecd9061efd1d981e5e90a6782b22958 Mon Sep 17 00:00:00 2001 From: PythonHackerr Date: Tue, 17 Dec 2024 11:25:10 -0500 Subject: [PATCH 10/10] Updated Documentation --- docs/sdk/sdk.mdx | 5 +++++ docs/sdk/unity.mdx | 32 ++++++++++++++++++-------------- package.json | 1 - 3 files changed, 23 insertions(+), 15 deletions(-) diff --git a/docs/sdk/sdk.mdx b/docs/sdk/sdk.mdx index 0509e9d71..dd74e9aad 100644 --- a/docs/sdk/sdk.mdx +++ b/docs/sdk/sdk.mdx @@ -56,4 +56,9 @@ Note that you can use our [Waypoint apps](/waypoint) for iOS and Android to test + + + + + diff --git a/docs/sdk/unity.mdx b/docs/sdk/unity.mdx index c44b95a0b..ffb9a5cf6 100644 --- a/docs/sdk/unity.mdx +++ b/docs/sdk/unity.mdx @@ -6,7 +6,9 @@ sidebar_position: 1 # Unity wrapper SDK -This is the documentation for the Unity wrapper/plugin, which provides a thin proxy layer for integrating existing native SDKs offering location tracking and geofencing services. Before integrating, review the native SDK documentation for iOS and Android to understand platform-specific requirements and features. +This is the documentation for the Unity wrapper/plugin. Before integrating, read the [native SDK documentation](/sdk) to familiarize yourself with the platform. + +Unity SDK provides a thin proxy layer for integrating existing native SDKs offering location tracking and geofencing services. See the source on GitHub [here](https://github.com/radarlabs/unity-radar). @@ -16,9 +18,9 @@ Scripts documentation and Demo scene overview can be found in project READMEs. To integrate the Unity SDK, download or clone the package and include it in your Unity project: -1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. Ensure it contains all the required files. -2. Import the ExternalDependencyManager for Unity (EDM4U). It is included in the project but you can get it from `Package Manager` or from [repo](https://github.com/googlesamples/unity-jar-resolver): It is required if you want to add and use iOS/Android dependencies directly in your project like: `Android specific libraries (e.g AARs)` or `iOS CocoaPods` -3. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the native SDK documentation. +1. Copy the `Plugins` folder (containing both Android and iOS native implementations) into the `Assets` directory of your Unity project. +2. Import the `ExternalDependencyManager` for Unity (EDM4U). It is included in the project but you can get it from `Package Manager` or from [repo](https://github.com/googlesamples/unity-jar-resolver): It is required if you want to add and use iOS/Android dependencies directly in your project like: `Android specific libraries (e.g AARs)` or `iOS CocoaPods` +3. Ensure that any required permissions or settings specific to location tracking and geofencing are configured on both iOS and Android, as outlined in the [native SDK documentation](/sdk). ### Supported Unity versions @@ -219,14 +221,11 @@ using RadarSDK; ### Calls to APIs -The Unity SDK exposes following APIs calls: -```bash -initialize, setUserId, getUserId, setMetadata, getLocation, trackVerified, startTrackingVerified, stopTracking, getVerifiedLocationToken, onTokenUpdated -``` -Look at ***RadarUsageExample.cs*** script for example usages +The Unity SDK exposes following APIs calls (See `RadarUsageExample.cs` for example usages): #### Initialize +When your app starts, initialize the SDK with your publishable API key, found on the [Settings page](https://radar.com/dashboard/settings). ```cs private void InitializeRadar() { @@ -237,6 +236,7 @@ private void InitializeRadar() #### SetUserId +You can also assign a custom `userId`, also called *External ID* in the dashboard. To set a custom `userId`, call: ```cs private void SetUserId(string userId) { @@ -246,6 +246,7 @@ private void SetUserId(string userId) #### SetMetadata +To set a dictionary of custom metadata for the user, call: ```cs private void SetMetadata(MetadataContainer metadata) { @@ -255,6 +256,7 @@ private void SetMetadata(MetadataContainer metadata) #### GetLocation +Get a single location update without sending it to the server: ```cs private Task GetLocation() { @@ -277,7 +279,7 @@ private Task GetLocation() ``` #### TrackVerified - +Call `Radar.TrackVerified()` or `Radar.StartTrackingVerifiedAsync()` to perform fraud and jurisdiction checks. ```cs private async Task TrackVerifiedAsync() { @@ -286,7 +288,7 @@ private async Task TrackVerifiedAsync() ``` #### StartTrackingVerified - +Call `Radar.TrackVerified()` or `Radar.StartTrackingVerifiedAsync()` to perform fraud and jurisdiction checks. ```cs private async Task StartTrackingVerifiedAsync() { @@ -295,6 +297,7 @@ private async Task StartTrackingVerifiedAsync() ``` #### StopTracking +To stop tracking the user's location in the background (e.g., when the user logs out). ```cs private async Task StopTrackingAsync() @@ -304,7 +307,7 @@ private async Task StopTrackingAsync() ``` #### GetVerifiedLocationToken - +Instead of calling `Radar.trackVerified()`, which always fetches a fresh location token, you can instead call `Radar.getVerifiedLocationToken()`, which returns a cached location token immediately if the last location token is still valid, or fetches a fresh location token if not. Once the native SDK retrieves the location, it sends the data back to Unity. On Android, this is done via RadarJavaProxy, and on iOS, it’s done via a delegate or callback defined in RadarUnityBridge.m ```cs private void GetVerifiedLocationToken() @@ -335,7 +338,8 @@ private IEnumerator GetVerifiedLocationTokenCoroutine() #### OnTokenUpdated -OnTokenUpdated callback +If you set a delegate on iOS with `Radar.setVerifiedDelegate()` or a receiver on Android with `Radar.setVerifiedReceiver()`, fresh location tokens are also delivered to `OnTokenUpdated` and `DidTokenUpdated` callbacks, respectively. + ```cs private void SetVerifiedReceiver() { @@ -393,7 +397,7 @@ Here’s an example of how to log errors using the SDK: ```csharp try { - Radar.SomeFunctionality(); + Radar.SetUserId(userId); } catch (Exception ex) { diff --git a/package.json b/package.json index c8f554cf4..98b5d94fe 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,6 @@ "@types/react": "^17.0.11", "@types/react-helmet": "^6.1.1", "@types/react-router-dom": "^5.1.7", - "cross-env": "^7.0.3", "ejs": "^3.1.6", "husky": "^4.3.8", "lint-staged": "^13.2.3",