Feature: Custom Event

[jinliu9508]

Description

One Line Summary

Introduce a new SDK feature: 'User.trackEvent', enabling clients to track custom events at the user level.

Details

Motivation

Clients often need to track events with custom data tied to individual users at any point during the app lifecycle. This feature addresses that need by providing a streamlined API, enhancing workflow flexibility and allowing for more precise user behavior analysis.

Scope

• Added a new API: User.trackEvent(name: String, properties: Map<String, Any>), which allows tracking a custom event with associated properties for the current user.
• Custom event operations are cached and retried following the same OperationRepo rules as other user-level operations. However, each trackEvent invocation triggers an immediate network request. Event batching by user is not currently supported but may be considered in a future update.
• Custom events are not persisted locally outside the operation system. They are not retrievable through the SDK after being sent. Clients may need to maintain their own copy if needed.
• Events exceeding 1MB in payload size are rejected and discarded. Payload chunking is not implemented in this alpha version.

Testing

Unit testing

Added 3 test units ensuring that calling the new API results in a successful backend operation.

• UserManagerTests: ensure the custom event controller call sendCustomEvent() with the correct name and properties.
• CustomEventBackendServiceTests: ensure the backend service sends the correct data for the testing event
• CustomEventOperationExecutorTests: ensure the executor correctly executes the custom event operation

Manual testing

• Test case: calling trackEvent with a null properties

OneSignal.getUser().trackEvent("empty event", null);

• Expect: Event tracked with only the os_sdk in properties

• Test case: calling trackEvent with an empty property map

Map<String, Object> empty = new HashMap<>();
OneSignal.getUser().trackEvent("empty event", empty);

• Expect: Event tracked with only the os_sdk in properties

• Test case: a simple event property

Map<String, Object> simple = Collections.singletonMap("promo_code", "NEW50");
OneSignal.getUser().trackEvent(name, simple);

• Expect: Event tracked with the correct properties

• Test case with complex nested properties

Map<String, Object> simple = Collections.singletonMap("promo_code", "NEW50");
Map<String, Object> nested = new HashMap<>();
nested.put("signed_up_with_email", true);
nested.put("products_viewed_count", 15);
nested.put("names", Map.of("a", Map.of("b", 5.2)));

Map<String, Object> complex = new HashMap<>();
complex.put("promo_code", "NEW50");
complex.put("additional_data", nested);
OneSignal.getUser().trackEvent(name, complex);

• Expect: Event tracked with all properties under a correct hierarchy
  Custom event data recorded on the dashboard:

"properties": {
    "additional_data": {
      "signed_up_with_email": true,
      "products_viewed_count": 15,
      "names": {
        "a": {
          "b": 5.2
        }
      }
    },
    "promo_code": "NEW50",
    "os_sdk": {
      "sdk": "050135",
      "device_os": "15",
      "type": "AndroidPush",
      "device_model": "sdk_gphone64_arm64",
      "device_type": "Android",
      "app_version": "1"
    }
  }

Affected code checklist

• Notifications
  • Display
  • Open
  • Push Processing
  • Confirm Deliveries
• Outcomes
• Sessions
• In-App Messaging
• REST API requests
• Public API changes

Checklist

Overview

• I have filled out all REQUIRED sections above
• PR does one thing
  • If it is hard to explain how any codes changes are related to each other then it most likely needs to be more than one PR
• Any Public API changes are explained in the PR details and conform to existing APIs

Testing

• I have included test coverage for these changes, or explained why they are not needed
• All automated tests pass, or I explained why that is not possible
• I have personally tested this on my device, or explained why that is not possible

Final pass

• Code is as readable as possible.
  • Simplify with less code, followed by splitting up code into well named functions and variables, followed by adding comments to the code.
• I have reviewed this PR myself, ensuring it meets each checklist item
  • WIP (Work In Progress) is ok, but explain what is still in progress and what you would like feedback on. Start the PR title with "WIP" to indicate this.

---

This change is