cz.xprees.event-logging 1.0.16 → 1.0.18

package/README.md

@@ -10,17 +10,30 @@ the [CF-Bucket - Log collector service](https://github.com/cyber-framework/cf-bu
 
 ## Installation
 
-Install the package using npm scoped registry in `Project Settings > Package Manager > Scoped Registries`
+Install the package using npm scoped registry in `Project Settings > Package Manager > Scoped Registries` (For more details
+see [Unity Docs - Use a scoped registry in your project](https://docs.unity3d.com/6000.2/Documentation/Manual/upm-scoped-use.html))
+
+`Packages/manifest.json`
 
 ```json
 {
-    "name": "NPM - xprees",
-    "url": "https://registry.npmjs.org",
-    "scopes": [
-        "cz.xprees"
+    "scopedRegistries": [
+        {
+            "name": "package.openupm.com",
+            "url": "https://package.openupm.com",
+            "scopes": [
+                "com.cysharp"
+            ]
+        },
+        {
+            "name": "NPM - xprees",
+            "url": "https://registry.npmjs.org",
+            "scopes": [
+                "cz.xprees"
+            ]
+        }
     ]
 }
-
 ```
 
 Then simply install the package using the Unity Package Manager using the _NPM - xprees_ scope or by the package name `cz.xprees.event-logging`.
@@ -30,4 +43,8 @@ Then simply install the package using the Unity Package Manager using the _NPM -
 The package will automatically define the script define symbol `XPREES_EVENT_LOGGING` in the project settings. This is used to enable the event
 logging functionality in your project and compatibility with other packages using event-logging capabilities.
 
+## Quick Start
 
+For a quick start, you can use the `EventLogManager` sample, that will give you a head start on how to log events in your project.
+Import the sample via the Package Manager UI by selecting the package and clicking on the _Import Sample_ button.
+Then you can use the `EventLogManager` component in your scene or just copy the script to your project and adjust to your need!

package/Samples~/EventLogManager/Scripts/EventLogManager.Api.cs

@@ -0,0 +1,109 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using Cysharp.Threading.Tasks;
+using UnityEngine;
+using Xprees.EventLogging.Api;
+using Xprees.EventLogging.Api.Model;
+
+namespace Xprees.EventLogging.Samples.Scripts
+{
+    // Partial class to handle API related functionality of the Event Log Manager.
+    public partial class EventLogManager
+    {
+        [Header("API Settings")]
+        [Tooltip("Event logging API URL to send the events to.")]
+        [SerializeField] private string apiUrl = "https://cf-collector.xprees.com/";
+
+        [Tooltip("How often to send the events to the API in seconds.")]
+        [Range(1, 300)]
+        [SerializeField] private int sendInterval = 10;
+
+        [Tooltip("Whether to warm up the API connection on start with a dummy call, to wake up the service.")]
+        [SerializeField] private bool warmupApiOnStart = true;
+
+        [Tooltip("Whenever to upload remaining event logs on application quit.")]
+        [SerializeField] private bool uploadOnDisable = true;
+
+        [Tooltip("Whenever to upload remaining event logs on application quit.")]
+        [SerializeField] private bool uploadOnQuit = true;
+
+        [Tooltip("Whenever the logs should be upload from editor.")]
+        [SerializeField] private bool dontSendInEditor = false;
+
+        [Tooltip("Whenever the manager should log into the console.")]
+        [SerializeField] private bool logInConsole = true;
+
+        private EventLoggingApi _api;
+
+        private void CreateApiInstance()
+        {
+            if (IsInvalidUrl(apiUrl))
+            {
+                Debug.LogError(
+                    $"{nameof(Xprees.EventLogging.Samples.Scripts.EventLogManager)} - Invalid API Url found!\n Using default one! {EventLoggingApi.DefaultEndpoint}",
+                    this);
+                _api = new EventLoggingApi();
+                return;
+            }
+
+            _api = new EventLoggingApi(apiUrl);
+        }
+
+        private void StartupApi(CancellationToken cancellationToken = default)
+        {
+            if (Application.isEditor && dontSendInEditor) return;
+            if (!warmupApiOnStart) return;
+
+            ConsoleLog("Warming up API...");
+            _api.Warmup(cancellationToken).Forget();
+        }
+
+        private bool IsInvalidUrl(string apiEndpoint) =>
+            string.IsNullOrEmpty(apiEndpoint) || !Uri.TryCreate(apiEndpoint, UriKind.Absolute, out _);
+
+        public async void Upload() => await UploadEvents(destroyCancellationToken);
+
+        public async UniTask<bool> UploadEvents(CancellationToken cancellationToken = default)
+        {
+            List<EventLog> logs;
+            lock (_collectedEventLogs)
+            {
+                logs = _collectedEventLogs.ToList();
+                ClearCollectedLogs();
+                TryToFixLogsUserWithCurrentIfMissing(logs);
+                if (logs.Count <= 0) return true; // nothing to upload skip it
+            }
+
+            if (Application.isEditor && dontSendInEditor)
+            {
+                ConsoleLog("Disabled upload in Editor, skipping upload.", this);
+                return true;
+            }
+
+            ConsoleLog($"Uploading {logs.Count.ToString()} event logs...", this);
+            var result = await _api.SendEventLogsBatch(logs, cancellationToken);
+
+            if (!result) // if upload failed, add logs back to the queue
+            {
+                lock (_collectedEventLogs) logs.ForEach(l => _collectedEventLogs.Add(l));
+            }
+
+            ConsoleLog($"Uploading {(result ? "Success" : "Failed")}.", this);
+            return result;
+        }
+
+        private void TryToFixLogsUserWithCurrentIfMissing(IEnumerable<EventLog> logs)
+        {
+            var currentUser = EventLoggingUser;
+            foreach (var log in logs)
+            {
+                if (log.user is null || string.IsNullOrEmpty(log.user.formId))
+                {
+                    log.user = currentUser;
+                }
+            }
+        }
+    }
+}

package/Samples~/EventLogManager/Scripts/EventLogManager.Api.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: e71b49a25d194423ae377505bf724ad0
+timeCreated: 1761647784

package/Samples~/EventLogManager/Scripts/EventLogManager.cs

@@ -0,0 +1,89 @@
+using System;
+using System.Collections.Concurrent;
+using UnityEngine;
+using Xprees.EventLogging.Api.Model;
+using Xprees.EventLogging.Extensions;
+using Xprees.EventLogging.ScriptableObjects;
+using Object = UnityEngine.Object;
+
+namespace Xprees.EventLogging.Samples.Scripts
+{
+    /// Local event log manager for elevator that collects and sends events to the event log api server.
+    [DisallowMultipleComponent]
+    public partial class EventLogManager : MonoBehaviour, IEventSenderService
+    {
+        [Header("Event Logging")]
+        [Tooltip(
+            "This is unique URL-SAFE ID for your project logs. "
+            + "Change it to your own project's ID, or you will mix logs with other projects using the same default ID. "
+            + "aka. Scenario name.")]
+        [SerializeField] private string projectId = "vr-mp-elevator";
+
+        [Tooltip("Reference to the user manager that provides user data for the logs.")]
+        [SerializeField] private EventUserManager userManager;
+
+        private User EventLoggingUser => userManager.CurrentUser;
+
+        private readonly ConcurrentBag<EventLog> _collectedEventLogs = new();
+
+        private void Start()
+        {
+            StartupApi();
+            StartPeriodicUpload();
+        }
+
+        private void OnEnable() => CreateApiInstance();
+
+        private async void OnDisable()
+        {
+            StopPeriodicUpload();
+            if (uploadOnDisable) await UploadEvents(destroyCancellationToken);
+        }
+
+        private async void OnApplicationQuit()
+        {
+            if (uploadOnQuit) await UploadEvents(destroyCancellationToken);
+        }
+
+        public void StartPeriodicUpload() => InvokeRepeating(nameof(Upload), sendInterval, sendInterval);
+
+        public void StopPeriodicUpload() => CancelInvoke(nameof(Upload));
+
+        public void LogEvent(EventSO loggedEvent)
+        {
+            SetCurrentScenarioToLoggedEventIfMissing(loggedEvent);
+            var user = EventLoggingUser;
+            if (string.IsNullOrEmpty(user.formId))
+            {
+                Debug.LogError($"{nameof(EventLogManager)} - Current user formId is null or empty! Resulting corrupted logs.", this);
+            }
+
+            if (loggedEvent == null || string.IsNullOrEmpty(loggedEvent.scenario))
+            {
+                ConsoleLog($"{nameof(EventLogManager)} - Scenario is null or empty! Throwing out the log. "
+                           + $"Event: \"{(loggedEvent != null ? loggedEvent.eventName : "None")}\"");
+                return;
+            }
+
+            var eventLog = loggedEvent.GenerateEventLog(user, DateTime.UtcNow);
+            lock (_collectedEventLogs) _collectedEventLogs.Add(eventLog);
+
+            ConsoleLog($"Logged event: {eventLog.@event}", this);
+        }
+
+        private void SetCurrentScenarioToLoggedEventIfMissing(EventSO loggedEvent)
+        {
+            if (!string.IsNullOrEmpty(loggedEvent.scenario)) return;
+            // Try to fill scenario from current scenario name
+            loggedEvent.scenario = projectId;
+        }
+
+        private void ClearCollectedLogs() => _collectedEventLogs.Clear();
+
+        private void ConsoleLog(string message, Object context = null)
+        {
+            if (!logInConsole) return;
+            Debug.Log(message, context);
+        }
+    }
+}

package/Samples~/EventLogManager/Scripts/EventLogManager.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 4097b66fb43d48cf965592e60ba7630c
+timeCreated: 1761647784

package/Samples~/EventLogManager/Scripts/EventUserManager.cs

@@ -0,0 +1,55 @@
+using System;
+using UnityEngine;
+using Xprees.EventLogging.Api.Model;
+
+namespace Xprees.EventLogging.Samples.Scripts
+{
+    /// Event user manager for the elevator experience.
+    /// Provides user data for event logging.
+    [DisallowMultipleComponent]
+    public class EventUserManager : MonoBehaviour, IEventUserSetupService
+    {
+        // Changed default prefix of player GUIDs to easier separate event users from your project.
+        private const string defaultPrefix = "event-logging-sample";
+
+        [Header("Settings")]
+        [Tooltip("Prefix for the generated user GUIDs. Can be used to identify users from. e.g., event-logging-sample")]
+        [SerializeField] private string guidPrefix = "vr-mp-elevator";
+
+        [Tooltip("Name of the player that will be used in event logs user.")]
+        [SerializeField] public string playerName = "player";
+
+        public User CurrentUser { get; set; }
+
+        private void Awake() => SetupUserIfNeeded();
+
+        public void SetFormId(string actorId)
+        {
+            SetupUserIfNeeded();
+            CurrentUser.formId = actorId;
+        }
+
+        public void SetName(string username)
+        {
+            SetupUserIfNeeded();
+            CurrentUser.name = username;
+        }
+
+        public void SetEmail(string email)
+        {
+            SetupUserIfNeeded();
+            CurrentUser.email = email;
+        }
+
+        private void SetupUserIfNeeded()
+        {
+            CurrentUser ??= new User
+            {
+                // Random unique user id
+                formId = $"{guidPrefix?.Trim() ?? defaultPrefix}-{Guid.NewGuid():D}",
+                name = playerName,
+                email = null,
+            };
+        }
+    }
+}

package/Samples~/EventLogManager/Scripts/EventUserManager.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 72eafbc27ff94a5389955011c35202f4
+timeCreated: 1761647784

package/Samples~/EventLogManager/Scripts/cz.xprees.event-logging.event-log-manager.asmdef

@@ -0,0 +1,9 @@
+{
+  "name": "cz.xprees.event-logging.event-log-manager",
+  "rootNamespace": "Xprees.EventLogging.Samples",
+  "references": [
+    "GUID:999c2ca78ab34358a1222750376a501c",
+    "GUID:2bc606c18a1a4f2cb45a7c51038804cf",
+    "GUID:f51ebe6a0ceec4240a699833d6309b23"
+  ]
+}

package/Samples~/EventLogManager/Scripts/cz.xprees.event-logging.event-log-manager.asmdef.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 4aed18caccf948e89fe197fe229be8f5
+timeCreated: 1761647785

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cz.xprees.event-logging",
   "displayName": "Event Logging",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "unity": "2021.3",
   "description": "This package provides a simple way to log events in your game.",
   "license": "Apache-2.0",
@@ -15,6 +15,13 @@
     "Event Logging",
     "ScriptableObjects"
   ],
+  "samples": [
+    {
+      "displayName": "Event log Manager Example",
+      "description": "Basic script for collecting and sending events to API. Great for getting started quickly and as a starting point for your own implementations.",
+      "path": "Samples~/EventLogManager"
+    }
+  ],
   "author": {
     "name": "xprees",
     "email": "xprees.developer@gmail.com",