Link Search Menu Expand Document

Snapyr For Unity SDK

The Snapyr Unity SDK makes it simple to create games or apps in Unity and build them for Android or iOS, connecting them to the Snapyr platform.

Snapyr supports Unity 2019.4 (latest LTS is Unity 2019.4.20f1)

Using the Unity SDK

Step 1: Install the Library

Visit the releases page of the Snapyr Unity SDK repository on Github: https://github.com/snapyrautomation/snapyr-sdk-unity/releases

Find the latest release and download the SDK plugin file, snapyr-sdk.unitypackage.

Import the package into your project: in Unity, click Assets => Import Package => Custom Packge… and select snapyr-sdk.unitypackage.

XCode / iOS Implementation Notes

  1. For Unity 2019.4 (our primary supported version of Unity) the Unity code is built as a framework (UnityFramework). If using an older version of Unity where code is not packaged as a framework, you should change the header in Libraries/Snapyr/Plugins/iOS/SnapyrUnityInterface.mm to be:
#import "Snapyr-Swift.h"

Instead of:

#import "UnityFramework/Snapyr-Swift.h"
  1. From Unity, build your project by going to File -> Build Settings.
    1. If iOS has not already been selected, select iOS and click “Switch Platform”.
    2. Click “Build” and select your build directory.
    3. Navigate to the build directory, and select the .xcodeproj file (typically Unity-iPhone.xcodeproj by default). Open this file to open the project in Xcode. Note that opening the directory itself, instead of the .xcodeproj, may lead to problems.
  2. The Snapyr SDK is currently built for development using physical iOS devices. Connect an iOS device to your Mac, and make sure it is selected as the target in the top of the Xcode window. Xcode Target

  3. At the PROJECT level under Build Settings, set the Objective-C Generated Interface Header Name under the Swift Compiler - General section to be Snapyr-Swift.h Project Settings

  4. Under the Unity-iPhone target, also make sure the Snapyr.framework is both linked…
    1. Select the Unity-iPhone target
    2. Go to “Build Phases” -> “Link Binary With Libraries” and click the + to add
    3. Select “Add Other” -> “Add Files…”
    4. Navigate to Frameworks/Snapyr/Plugins/iOS, select Snapyr.framework, and click Open.
  5. … and Embedded (with Code Sign on Copy):
    1. Also under the Unity-iPhone target’s “Build Phases” section, go to “Embed Frameworks” and click the + to add
    2. Type snapyr to filter, and select Unity-iPhone/Frameworks/Snapyr/Plugins/iOS/Snapyr.framework
    3. Make sure “Code Sign On Copy” is checked. Unity-iPhone Target Settings
  6. If you encounter a build error saying “Building for iOS, but the linked and embedded framework ‘Snapyr.framework’ was built for iOS + iOS Simulator”, follow these steps:
    1. Under the Unity-iPhone target, go to “Build Settings” -> “Build Options”
    2. Find “Validate Workspace” and select “Yes” (do not select “Yes (error)”)
    3. This will allow builds to succeed with a warning, instead of error, regarding the build platform.
  7. Finally, be sure to implement the push notification code directly, to ensure that push notifications can be received and tracked. See the Unity iOS push notification guide for details.

Android Studio Notes

  1. Export your project to Android Studio. This is good practice for debugging: Android Build Settings

  2. Add the below dependencies in the build.gradle file of your_project.unityLibrary, then sync Gradle. The project should now build successfully.
     dependencies {
         implementation('androidx.lifecycle:lifecycle-process:2.2.0')
         implementation('androidx.lifecycle:lifecycle-common-java8:2.2.0')
         implementation('androidx.constraintlayout:constraintlayout:2.1.4')
    
         implementation('androidx.core:core')
         implementation('androidx.appcompat:appcompat:1.3.0')
    
         implementation platform('com.google.firebase:firebase-bom:27.1.0')
         implementation('com.google.firebase:firebase-messaging')
     }
    
  3. Also be sure to implement the push notification code directly by hand, to ensure that push notifications can be received and tracked. See the Android Push Setup Docs.

Step 2. Initialize

You can initialize the SDK wherever you wish, but generally the best place is in your main game’s Start() method. Note that initialization should happen only once per run of the game. You can check SnapyrWrapper.isInitialized to determine whether initialization has already occurred.

NOTE: Snapyr push notification tracking relies on the Snapyr SDK having been initialized. If the SDK is not initialized at the beginning of your game’s launch, Snapyr will be unable to track certain startup-time information such as notification taps and application opens. To ensure that this data is tracked accurately, please be sure to initialize the SDK as early as possible in your game’s lifecycle - even if no Track() or Identify() calls are made until later.

Be sure to include the library in any class that uses it:

using Snapyr;
using Snapyr.Types;

You’ll need your app’s Snapyr Write Key. To obtain your write key, please contact Snapyr Customer Service.

if (!SnapyrWrapper.isInitialized) {
    SnapyrWrapper.I.Initialize("WRITE_KEY",
        new SnapyrConfiguration.Builder()
            // Enable this to automatically track things like app opens + closes
            .trackApplicationLifecycleEvents(true)
            // Enable this to have the underlying native SDK automatically handle push notifications (Android only)
            .enableSnapyrPushHandling(true)
            .recordScreenViews(true)
            .build()
        );
}

You can also automatically track screen views as well as lifecycle events such as Application Opened, Application Installed, Application Updated to start quickly with core events. These are enabled by default.

Main Snapyr SDK Calls

Identify

This lets you setup information about the current user and tie that individual to all actions taken. You can set traits for a specific user and these traits will be tied to every tracking action taken. Note that if you do not call Identify, the Snapyr SDK will generate an AnonymousID for the user.

var traits = new Traits();
traits.Add("first_name", "Alice");
traits.Add("player_type", "standard");
SnapyrWrapper.I.Identify("userId", traits);

Snapyr recommends that you make an Identify call once when the user first registers or logs in to his / her account, and then call Identify again if traits are added – for example if the user links her account to Facebook or email and you now have desired data. Snapyr will merge any old traits with new ones and update any traits that use the same key.

Remember, you can replace the properties and traits in the code samples with variables that represent the data you actually collected.

The Identify call has the following fields:

userId String, optional The unique ID for this user that your app uses.
traits Traits, optional A map of traits about the user, such as their first name, Facebook ID, email address, etc. This map must be flat. All keys are strings, and supported value types are string, boolean, integer, and float.

The SDK automatically sends the userId and anonymousId as traits.

Track

The Track call is at the heart of Snapyr and allows you to keep track of events or actions your users perform. Every event can also have associated properties.

var props = new Properties();
props.Add("sceneId", "123");
SnapyrWrapper.I.SnapyrTrack("testevent", props);

By default, Snapyr tracks a few key common events automatically such as the Application Installed, Application Updated and Application Opened. You can turn automatic tracking off during initialization by setting the trackApplicationLifecycleEvents parameter to false.

You might also want to track events that indicate key spots hit such as Registered, Logged In, Complete Tutorial, or Purchased an Item.

Dictionary<string, string> params = new Dictionary<string, string>();
params.Add("gold_bars", 10);
params.Add("currency", "USD");
SnapyrWrapper.I.SnapyrTrack("purchase_event",params);

The Track call includes the following fields:

name String, required A name for the tracked action.
properties Properties, optional A map of properties for this action, e.g. revenue if the action was a purchase. This map must be flat. All keys are strings, and supported value types are string, boolean, integer, and float.

Screen

The Screen method lets you record whenever a user opens up a new screen of your mobile app, along with optional extra information about the page being viewed.

SnapyrWrapper.I.Screen("screen_name");

You’ll usually find it useful to record a screen event whenever the user opens a new popup or screen/screen in your app. E.g.:

SnapyrWrapper.I.Screen("gold store");

The screen call has the following fields:

name String,optional A name for the screen.

Reset

The Reset method can clear the SDK’s internal data for the current user, such as user traits. This is useful if a user logs out so that multiple users with different identities can be tracked properly. Note that when you call Reset, Snapyr will assign the new user an AnonymousID until a new id is explicitly set via the Identify method.

SnapyrWrapper.I.Reset();

Debug Logging

If you want to dive deeper into the Snapyr SDK and all of the events it is sending, you can enable logging.

SnapyrWrapper.I.SnapyrDebug(true);

We recommend setting debug to false for the production build of your app or game.

Opt-out

Due to various laws or age groups, you may need to opt out of analytics tracking. You can turn tracking off using:

SnapyrWrapper.I.OptOut();

This flag persists across device reboots, so you can call it once (such as in a settings screen) and Snapyr will remember your decision.

Enjoy!


Table of contents