Download Unity Plug-in for iOS and Android 4.x SDK

Adobe® Marketing Cloud
Unity Plug-in for iOS and Android 4.x SDK
Contents
Unity Plug-in for iOS and Android 4.x SDK.....................................................................3
Building Your Project.......................................................................................................4
Making Calls to the Library..............................................................................................5
Implement Lifecycle.........................................................................................................6
ADBMobile.cs Methods....................................................................................................7
Enumerations..................................................................................................................14
Last updated 2/5/2016
Unity Plug-in for iOS and Android 4.x SDK
Unity Plug-in for iOS and Android 4.x SDK
Unity Plug-in for iOS and Android 4.x SDK
This Plug-in lets you send Adobe Analytics calls from your Unity applications.
Updated February 5, 2016
• Getting Started
• Importing the ADBMobile plug-in to your Unity project
Getting Started
Download the ADBMobile.unitypackage file from GitHub or Developer Connection.
ADBMobile.unitypackage contents
• Assets (root)
• ADBMobile
• Demo
• ADBMobileDemo.cs
• BooDemo.boo
• BooScene.unity
• CSharpScene.unity
• JavaScriptDemo.js
• JavaScriptScene.unity
• SecondScene.unity
• SecondSceneScript.cs
• Plugins
• ADBMobile.cs
• Android
• adobeMobileLibrary-{version}.jar
• AndroidManifest.xml
• assets
• ADBMobileConfig.json
• iOS
• ADBMobile.h
• ADBMobileConfig.json
• ADBMobileWrapper.h
• ADBMobileWrapper.mm
• AdobeMobileLibrary.a
Optional folders: The Demo folder contains Unity scenes and sample code for each of the supported scripting languages.
Importing the ADBMobile plug-in to your Unity project
1. Open your Unity project.
2. Double-click ADBMobile.unitypackage.
3. Select the folders that you want to import.
3
Building Your Project
4
Building Your Project
Information to help you build iOS and Android applications using the Unity plugin.
iOS
When you build for iOS, an Xcode Project is created. By default, the ADBMobileWrapper.mm and AdobeMobileLibrary.a
files will be in your new project's Libraries group. Perform the following manual steps required to build you app:
1. Add your ADBMobileConfig.json file to the project.
Ensure that it is a member of the build any targets necessary.
2. In the Build Phases tab of your project, add a link to the following libraries:
• SystemConfiguration.framework (this one may be linked already)
• libsqlite3.0.dylib
Note: If you want to use Local Notification In-App messages from the SDK, you must call
ADBMobile.EnableLocalNotifications(); from the Start method in your first Unity Scene.
Android
When you build for Android, the apk file already includes the ADBMobileConfig.json file in the correct location. By
default, the AndroidManifest.xml file in your /Plugins/Android folder is also used.
If you need to use your own custom manifest file, the following changes should be added.
Add permissions for:
• INTERNET
• ACCESS_NETWORK_STATE
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Add the following activity and receiver if you are using In-app messaging:
<activity android:name="com.adobe.mobile.MessageFullScreenActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar" />
<receiver android:name="com.adobe.mobile.MessageNotificationHandler" />
Add the following receiver if you are using acquisition:
<receiver android:name="com.your.package.name.GPBroadcastReceiver" android:exported="true">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>
Making Calls to the Library
Making Calls to the Library
Information to help you make calls to the library with iOS and Android applications using the Unity plugin.
When you want to make calls to the plug-in from your scripts, you must import the namespace.
• C#: using com.adobe.mobile;
• JavaScript: import com.adobe.mobile;
• boo: import com.adobe.mobile;
After you have imported the namespace, you can make calls directly to the plug-in via the static methods of the ADBMobile
class.
5
Implement Lifecycle
6
Implement Lifecycle
Information to help you implement Lifecycle metrics in your Unity applications.
See Lifecycle Metrics for the metrics and dimensions that can be measured automatically by the mobile library after lifecycle is
implemented.
iOS
For iOS, lifecycle metrics are automatically collected.
Android
In your Unity script, you set the application context for the Android SDK. Add the following code to the Awake() function of
your FIRST scene:
void Awake()
{
...
ADBMobile.SetContext();
...
}
To collect lifecycle metrics, add the following code to all of your scene scripts:
void OnEnable()
{
...
ADBMobile.CollectLifecycleData ();
...
}
void OnDisable()
{
...
ADBMobile.PauseCollectingLifecycleData ();
...
}
void OnApplicationPause(bool isPaused)
{
...
if (isPaused) {
ADBMobile.PauseCollectingLifecycleData ();
}
else {
ADBMobile.CollectLifecycleData();
}
...
}
ADBMobile.cs Methods
7
ADBMobile.cs Methods
List of ADBMobile.cs methods for Unity applications.
Configuration Methods
Method Name
Description
CollectLifecycleData
Indicates to the SDK that lifecycle data should be collected for use across all solutions in the SDK.
See Lifecycle Metrics.
Syntax:
public static void CollectLifecycleData();
Example:
ADBMobile.CollectLifecycleData();
EnableLocalNotifications Enable local notifications in your app.
(iOS only)
Syntax:
public static void EnableLocalNotifications();
Example:
ADBMobile.EnableLocalNotifications();
GetDebugLogging
Returns the current debug logging preference. Default: false
Syntax:
public static bool GetDebugLogging();
Example:
var debugEnabled = ADBMobile.GetDebugLogging();
GetLifetimeValue
Returns the lifetime value of the current user.
Syntax:
public static double GetLifetimeValue();
Example:
var lifetimeValue = ADBMobile.GetLifetimeValue();
GetPrivacyStatus
Returns the enum representation of the privacy status for current user.
MOBILE_PRIVACY_STATUS_OPT_IN: Hits are sent immediately.
MOBILE_PRIVACY_STATUS_OPT_OUT: Hits are discarded.
MOBILE_PRIVACY_STATUS_UNKNOWN: If offline tracking is enabled, hits are saved until the
privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If offline
tracking is not enabled, hits are discarded until the privacy status changes to opt in.
Default: The default value is set in ADBMobileConfig.json.
ADBMobile.cs Methods
Method Name
8
Description
Syntax:
public static ADBPrivacyStatus GetPrivacyStatus();
Example:
var privacyStatus = ADBMobile.GetPrivacyStatus();
GetUserIdentifier
Returns the custom user identifier if a custom identifier has been set. Returns null if a custom
identifier is not set.
Default: null
Syntax:
public static string GetUserIdentifier();
Example:
var userId = ADBMobile.GetUserIdentifier();
GetVersion
Gets the library version.
Syntax:
public static string GetVersion();
Example:
var version = ADBMobile.GetVersion();
KeepLifecycleSessionAlive Indicates to the SDK that your next resume from background should not start a new session, regardless
(iOS only)
of the value of lifecycle session timeout in your config file.
Note: This method is intended to be used for apps that register for notifications while in the
background and should only be called from your code that runs while your app is in the background.
Syntax:
public static void KeepLifecycleSessionAlive();
Example:
ADBMobile.KeepLifecycleSessionAlive();
PauseCollectingLifecycleData Indicates to the SDK that your app is paused, so that lifecycle metrics are calculated correctly. For
(Android only)
example, on pause collects a timestamp to determine previous session length. This also sets a flag
so that lifecycle correctly knows that the app did not crash. See Lifecycle Metrics.
Syntax:
public static void PauseCollectingLifecycleData();
Example:
ADBMobile.PauseCollectingLifecycleData();
SetContext (Android
only)
Indicates to the SDK that it should set its application context from the UnityPlayer's current activity
ADBMobile.cs Methods
Method Name
9
Description
Syntax:
public static void SetContext();
Example:
ADBMobile.SetContext();
SetDebugLogging
Sets the debug logging preference to enabled.
Syntax:
public static void SetDebugLogging (bool enabled);
Example:
ADBMobile.SetDebugLogging(true);
SetPrivacyStatus
Sets the privacy status for the current user to status. Set to one of the following values:
MOBILE_PRIVACY_STATUS_OPT_IN: Hits are sent immediately.
MOBILE_PRIVACY_STATUS_OPT_OUT: Hits are discarded.
MOBILE_PRIVACY_STATUS_UNKNOWN: If offline tracking is enabled, hits are saved until the
privacy status changes to opt-in (then hits are sent) or opt-out (then hits are discarded). If offline
tracking is not enabled, hits are discarded until the privacy status changes to opt in.
Syntax:
public static void SetPrivacyStatus(ADBPrivacyStatusstatus);
Example:
ADBMobile.SetPrivacyStatus(ADBMobile.ADBPrivacyStatus.MOBILE_PRIVACY_STATUS_OPT_IN);
SetUserIdentifier
Sets the user identifier to userId.
Syntax:
public static void SetUserIdentifier(string userId);
Example:
ADBMobile.SetUserIdentifier("myCustomUserId");
Analytics Methods
Method
Description
GetTrackingIdentifier
Retrieves the analytics tracking identifier.
Syntax:
public static string GetTrackingIdentifier();
Example:
var trackingId = ADBMobile.GetTrackingIdentifier();
ADBMobile.cs Methods
10
Method
Description
TrackState
Tracks an app state with optional context data. States are the views that are available in your
app, such as "title screen", "level 1", "pause", and so on. These states are similar to pages on a
website, and TrackState calls increment page views.
If state is empty, it displays as app name app version (build) in reports. If you see this value in
reports, make sure you are setting state in each TrackState call.
Note: This is the only tracking call that increments page views.
Syntax:
public static void TrackState(string state, Dictionary<string, object>
cdata);
Example:
var contextData = new Dictionary<string, object>);
contextData.Add ("user", "jim");
ADBMobile.TrackState("title screen", contextData);
TrackAction
Tracks an action in your app. Actions are the things that happen in your app that you want
to measure, such as "deaths", "level gained", "feed subscriptions", and other metrics.
Note: If you have code that might run while the app is in the background (for example, a
background data retrieval), use trackActionFromBackground instead.
Syntax:
public static void TrackAction(string action, Dictionary<string,
object> cdata);
Example:
ADBMobile.TrackAction("level gained", null);
TrackActionFromBackground Tracks an action that occurred in the background. This suppresses lifecycle events from firing
(iOS only)
in certain scenarios.
Note: This method should only be called in code that runs while your app is in the background.
Syntax:
public static void TrackActionFromBackground(string action,
Dictionary<string, object> cdata);
Example:
ADBMobile.TrackActionFromBackground("majorLocationChange", null);
TrackLocation
Sends the current latitude and longitude coordinates. Also uses points of interest defined in
the ADBMobileConfig.json file to determine if the location provided as a parameter is within
any of your POI. If the current coordinates are within a defined POI, a context data variable
is populated and sent with the TrackLocation call.
Syntax:
public static void TrackLocation(float latValue, float lonValue,
Dictionary<string, object> cdata);
ADBMobile.cs Methods
Method
11
Description
Example:
ADBMobile.TrackLocation(28.418649, -81.581324, null);
TrackBeacon
Tracks when a users enters proximity of a beacon.
Syntax:
public static void TrackBeacon(int major, int minor, string uuid,
ADBBeaconProximity proximity, Dictionary<string, object> cdata);
Example:
ADBMobile.TrackBeacon(1337,
4334,"2d83ad40-a346-11e4-9dc0-0002a5d5c51b",
ADBMobile.ADBBeaconProximity.PROXIMITY_FAR, null);
TrackingClearCurrentBeacon
Clears beacons data after a user leaves the proximity of the beacon.
Syntax:
public static void TrackingClearCurrentBeacon();
Example:
ADBMobile.TrackingClearCurrentBeacon();
TrackLifetimeValueIncrease
Adds amount to the user's lifetime value.
Syntax:
public static void TrackLifetimeValueIncrease(double amount,
Dictionary<string, object> cdata);
Example:
ADBMobile.TrackLifetimeValueIncrease(5, null);
TrackTimedActionStart
Start a timed action with name action.
If you call this method for an action that has already started, the previous timed action is
overwritten.
Note: This call does not send a hit.
Syntax:
public static void TrackTimedActionStart(string action,
Dictionary<string, object> cdata);
Example:
ADBMobile.TrackTimedActionStart("level2", null);
TrackTimedActionUpdate
Pass in data to update the context data associated with the given action.
The data passed in is appended to the existing data for the given action, and overwrites the
data if the same key is already defined for action.
Note: This call does not send a hit.
ADBMobile.cs Methods
Method
12
Description
Syntax:
public static void TrackTimedActionUpdate(string action,
Dictionary<string, object> cdata);
Example:
var contextData = new Dictionary<string, object>();
contextData.Add("checkpoint", "1:32");
ADBMobile.TrackTimedActionUpdate("level2", contextData);
TrackTimedActionEnd
End a timed action.
Syntax:
public static void TrackTimedActionEnd(string action);
ADBMobile.TrackTimedActionEnd("level2");
TrackingTimedActionExists
Returns whether or not a timed action is in progress.
Syntax:
public static bool TrackingTimedActionExists(string action);
Example:
var level2InProgress = ADBMobile.TrackingTimedActionExists("level2");
TrackingSendQueuedHits
Forces the library to send all hits in the offline queue no matter how many are currently
queued.
Syntax:
public static void TrackingSendQueuedHits();
Example:
ADBMobile.TrackingSendQueuedHits();
TrackingClearQueue
Clears all hits from the offline queue.
Syntax:
public static void TrackingClearQueue();
Example:
ADBMobile.TrackingClearQueue();
TrackingGetQueueSize
Retrieves the number of hits currently in the offline queue.
Syntax:
public static int TrackingGetQueueSize();
Example:
var queueSize = ADBMobile.TrackingGetQueueSize();
Marketing Cloud ID Methods
ADBMobile.cs Methods
13
Method
Description
GetMarketingCloudID
Retrieves the Marketing Cloud visitor ID from the visitor ID service.
Syntax:
public static string GetMarketingCloudID();
Example:
var mcid = ADBMobile.GetMarketingCloudID();
VisitorSyncIdentifiers
Along with the Marketing Cloud visitor ID, you can set additional customer IDs to associate
with each visitor. The Visitor API accepts multiple Customer IDs for the same visitor, along
with a customer type identifier to separate the scope of the different customer IDs. This
method corresponds to setCustomerIDs in the JavaScript library.
Syntax:
public static void VisitorSyncIdentifiers(Dictionary<string, object>
identifiers);
Example:
var ids = new Dictionary<string, object> ();
ids.Add ("player1", "jimbob");
ADBMobile.VisitorSyncIdentifiers(ids);
Enumerations
Enumerations
List of enumerations for use in Unity applications.
ADBPrivacyStatus
• MOBILE_PRIVACY_STATUS_OPT_IN
• MOBILE_PRIVACY_STATUS_OPT_OUT
• MOBILE_PRIVACY_STATUS_UNKNOWN
ADBBeaconProximity
• PROXIMITY_UNKNOWN
• PROXIMITY_IMMEDIATE
• PROXIMITY_NEAR
• PROXIMITY_FAR
14