Close

Unity3D Plugin

Omniata Unity Plugin includes a C# file (Omniata.cs) to utilize the Omniata iOS SDK and Omniata Android SDK. If you want to use any feature of Omniata iOS SDK or Omniata Android SDK that the Unity Plugin does not support, you can have a look at the Omniata.cs class to see how to make the iOS SDK or Android SDK methods visible in Unity.

As the native SDKs handle sending of events and Channel API requests, the functionality of the SDKs is identical to their functionality as if they were used as such, i.e. without Unity3D. This means for example that the om_sdk_version is the native SDK version. The Unity Plugin adds a parameter om_unity_sdk_version with the correct value (in om_load) to identify that the event is from Unity Plugin and to identify the version of the Unity Plugin.

The Unity Plugin supports the usage of iOS and Android environment. The Webplayer is partly supported without establishing the events queue.

Events tracking in the Editor is not supported at the moment since this plugin is made for calling native iOS and Android SDK methods.

Content:

Installation and Upgrade

The latest available plugin can be found below.

Platform Links Version Release Date
Unity3D Source code
API details
1.3.23 15 Dec 2016

The installation of Omniata Unity3D Plugin in your Unity3D application starts with the import of the unitypackage plugin file, in Unity go to Assets -> Import Package -> Custom Package. There is an example project in the package, it’s optional to import that.

To update to the latest version remove the directory Omniata from your Unity project, the OmniataiOSPlugin.m file inside of Plugins/iOS and Omniata inside of Editor. Remove also AndroidManifest.xml and Omniata-android-sdk.jar inside of Plugins/Android. Then proceed with the install instructions above.

Once the Omniata Unity Plugin code has been installed in your application, you can start integrating it.

Integrating the Unity3D Plugin

Initialization

The code file Omniata.cs is by default located in Assets/Omniata with the namespace OmniataSDK. The parameters need to be given are the API key, UID and organization name.

The value in <ORG_NAME> is the organization part of the URL you use to access Omniata Panel, for example in https://acme.panel.omniata.com the <ORG_NAME> value would be “acme”. The same principle applies to <USER_ID> which is your in-app user identifier and <API_KEY> which is the qualifier for the application and environment of the current build.

There are two ways to initialize the Omniata instance:

  1. Add Omniata.prefab as a Component to your scene and set the API_KEY, UID, ORG and corresponding loglevel needed. The Awake method inside of Omniata.cs will be called to initialize Omniata once. After that you can call the instance of Omniata and start using the API methods.

  2. Another way is “Start Manually”, check the “Start Manually” inside of Omniata.prefab, after import of the Omniata library, the parameters can be passed manually.

Since this plugin is based on Omniata iOS and Android SDK, in iOS SDK the appDidLaunch method can be called multiple times but only the first call will be effective. While in Android SDK the appDidLaunch method can be called multiple times and the last call will override the previous call.

You can use the following template to initialize the plugin:

// Import omniata library
using OmniataSDK;
// Get the instance of Omniata
Omniata.Instance.appDidLaunch("a514370d", "uidtest", "testorg", Omniata.LogLevel.Debug);

To initialize with a custom API endpoint you can use:

// Import omniata library
using OmniataSDK;
// Get the instance of Omniata. 
// Send events to customized Event API.
// The event API should be baseURL+"/event?"
// The channel API should be baseURL+"/channel?"
Omniata.Instance.appDidLaunch("a514370d", "uidtest", "testorg", Omniata.LogLevel.Debug, "customizedurl.omniata.com");

Configuration

The log level can be set for both iOS and Android. The level value is Verbose, Debug, Info, Warn, Error and Assert. The level can be set either in the Omniata.prefab or by using the SetOmLoglevel method.

The plugin also includes a basic version of all the features for testing of other platforms. There is no events queue inside of the implementation. The HTTP GET request is sent by using the StartCoroutine method.

Tracking Events

Standard events have their own build-in method for tracking. Custom events can be tracked using a generic method specified below.

Event Method When to call
Load Omniata.Instance.TrackOmLoad(); Whenever the app starts or is brought to foreground.
Revenue omniata.TrackOmRevenue(total,currency_code); For verified in-app purchases only. Three character currency code should follow ISO-4217 specifications. The Omniata SDK does not validate or verify purchases.
Advertiser Id Omniata.Instance.TrackOmAdvertiserID(parameters); Upon first load of the application ever. When needed in case the AdId changes. See below for more details.
Custom Omniata.Instance.TrackOm(type,parameters); When the target action or event is detected.

To track the advertiser ID you can use the following as a template:

// Tracking Advertiser ID
Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters.Add("track_tool", "omniata_unity_sdk");
Omniata.Instance.TrackOmAdvertiserID(parameters);

To register custom events parameters use for example:

// Tracking a Customized Event
Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters.Add("app", "testapp");
parameters.Add("attack.attacker_won", "0");
string type="testing_type";
Omniata.Instance.TrackOm(type,parameters);

Additionally, to add custom parameters to any method you can pass an additional parameter such that:

// Track load with additional parameters
Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters.Add("para", "testpara");
Omniata.Instance.TrackOmLoad(parameters);

The plugin will send events only when there is network connectivity. If there is no network connectivity, the events will be added to the queue and be send one by one once the network is back. Check the iOS and Android SDK sections for details. For other platforms, Omniata.cs will start a new coroutine with StartCoroutine method and use the send events method.

Requesting Content

Channel message loading supports only iOS for now, and the message can be seen in the console of the Xcode. For other platforms other than iOS and Android, a similar method of Channel API calling can also be used. An usage example can be found below:

// Load channel message
int ChannelId = 40;
Omniata.Instance.LoadOmChannelMessage(ChannelId); //load message

Working With Push Notifications

To enable push notification, Omniata Unity Plugin supports sending the token to Omniata.

iOS

Use the embedded Unity NotificationServices, which can easily register device at apple APNS and get the token, usage example:

byte[] token = NotificationServices.deviceToken;
Omniata.Instance.EnablePushNotificationsFromTokenBytes(token);

Android

There are Unity GCM extensions by default. Check the GCM folder under Plugins, gcm.jar and unitygcmplugin.jar under Plugin/Android, usage example:

GCM.SetRegisteredCallback ((string registrationId) => {
    Omniata.Instance.EnableOmPushNotifications(registrationId);
});

Detail of GCM extensions can be found for unity-gcm and unity-gcm-guide. There is also a tool available to test with GCM.

Implementation Details

iOS

The plugin uses the open source XUPorter project, located inside of the Editor folder of the Unity project, to add the iOS framework automatically into the Xcode project during the building process, since XUPorter does not support adding external framework into “Frameworks” repository for now, the plugin creates a new repository “Omniata” and adds our iOS SDK inside.

The plugin exposes the iOS NSLog method from iOS with P as a tag for debugging, you can check the log message after build Unity project to Xcode project.

Android

The plugin exposes the native Java methods from the Android SDK. The SDK asks for two permissions in AndroidManifest.xml file, android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE. The following meta element needs to be included inside of application node:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

The plugin includes google-play-services_lib folder since it is needed to get the Google Advertiser ID, the folder can be found in the following path:

<Android SDK PATH>/extras/google/google_play_services/libproject/google-play-services_lib

When building to Android project, the “package” name inside of AndroidManifest.xml should be the same with the Bundle Identifier name in the Player Settings of the Unity project. Check the example project for more details.

The plugin exposes the Android Log.i method with “Omniata” as a tag for debugging, you can check the log message inside of a Eclipse LogCat.

This article was last updated on April 21, 2017 15:25. If you didn't find your answer here, search for another article or contact our support to get in touch.