Create your first session
Now that you've got Embrace linked and know how to login to the Embrace dashboard, it's time to collect your first session.
Embrace always uploads sessions on subsequent launches. This means the general process we're going to follow to collect our first session is:
- Import the Embrace module
- Add a start call to the Embrace SDK
- End the Startup Moment
- Build and run our application
- Verify Embrace started via the logs
- Trigger a session upload
- Close or send the application to the background
- Launch the application to the foreground
- Verify that our first session was uploaded to Embrace by checking the dashboard
Let's start by importing the Embrace module. Embrace on Unity is accessible via a singleton C# class called
Embrace in the
EmbraceSDK namespace. Simply add this line to the top of any C# script you'd like to use with Embrace:
You will then access the shared instance of this class from anywhere in your program using the prefix:
From there you can call any public method on the API.
Our SDK has three runtime modes:
Android- in this mode Embrace logs to logcat. This mode is only activated if your build target is currently Android.
iOS- in this mode Embrace logs to the system console. This mode is only activated in your build target is iOS.
Editor- in this mode Embrace logs to the Unity console. This mode is active when you run inside the editor regardless of build target. Embrace only logs the actions it would perform. No data is uploaded while running in the editor.
For all other build targets, the result of Embrace API calls are no-ops. You can make calls to the Embrace SDK in shared code, but on platforms like Windows or MacOS those calls will do nothing and no data is uploaded to Embrace.
Add a start call
Embrace does nothing until its start method has been called. Find the place in your project where you initialize other third party SDKs or some other good entry point and add the following code:
It is important that this call be made as early as possible in the lifecycle of your application to ensure we can collect as much relevant data as possible. Additionally, Embrace has taken great care to ensure we can operate alongside any other third party SDKs. If Embrace is initialized first, then our code can set things up to ensure that everyone can interoperate successfully in your application.
End the Startup Moment
Finally, make sure to end the special "startup" moment that Embrace uses to track app launch performance. You can end this moment anywhere you choose. We recommend placing the call as close to the point that your UI is ready for use as possible, as doing so will give you the most accurate picture of the performance your users are experiencing with app launch.
This moment is used to track both launch performance and launch abandonment. The latter is the number of users who close the app before the launch finishes. To correctly track this, it is critical that all code paths end the startup moment eventually. For example, if your app can launch via a push notification, ensure that path also ends the startup moment or you may see inaccurate abandonment data.
Build and Run Your Application
You're now ready to build and run your application. Assuming the app launches correctly, pay attention to the system logging and look for Embrace to print out its version number.
[Embrace] Embrace SDK enabled. Version: 1.18.2
If you encounter any errors, please get in touch on Slack and we can help you out.
If you see a log line like this, you've succeeded in integrating Embrace with your application. Let's trigger a session upload and verify this in the dashboard.
Trigger a Session Upload
To trigger a session upload, simply send the application to the background by pressing the device's "home" button. Typically the SDK will be given sufficient time to upload the session as the app is going to the background, but sometimes the OS will not allow the app to complete the upload in the background. To ensure the session was uploaded, launch the application again. Refresh the dashboard in your browser and you should now see that you've moved on to the next step.
Congratulations! At this point you've completed a basic integration of Embrace. Embrace is already collecting interesting data from your application. You can see this data by browsing around the timeline page for the session you just captured.