API reference

Everything is in the GrovsSDK namespace. All members are static on Grovs, except GrovsUnityIAP and the types.

using GrovsSDK;

• No init call. The native SDK starts before Unity with the values from Project Settings.
• Threads. Call the API from the Unity main thread. Every Task completes, and every callback and event runs, on the main thread. The one exception is ShouldShowInAppMessage.
• Tasks or callbacks. Each async call has a Task version and a callback version. A failed task throws GrovsException. The callback gets the GrovsError instead, or null on success. Pending tasks have no timeout.
• Not started. If the native SDK didn't start (an empty API key, say), other calls do nothing and async calls fail with SdkNotInitialized.
• Editor and other platforms. Calls go to a stub that logs once per method and does nothing. Link calls fail with UnsupportedPlatform, purchase calls resolve false.

At a glance

Setup

SdkVersion

public static string SdkVersion { get; }

The Unity package version, "1.0.0". Not the native SDK version.

IsSupportedPlatform

public static bool IsSupportedPlatform { get; }

true on iOS and Android players. false in the Editor and on other platforms, and when the native bridge failed to start.

SetLogLevel

public static void SetLogLevel(GrovsLogLevel level)

Sets the native log level at runtime. The launch level comes from Log level in Project Settings (default Error). Android has no warn level, so Warn logs at Info there.

ErrorOccurred

public static event Action<GrovsError> ErrorOccurred

Errors that have no other place to be reported. Failed tasks and callbacks carry their own error.

• iOS: every asynchronous native SDK error.
• Android: in-app message failures and bridge errors only.

An exception thrown by a handler is logged and doesn't stop the other handlers.

Consent

See Privacy & Consent.

SetEnabled

public static void SetEnabled(bool enabled)

Turns collection on or off and saves the choice on the device. The saved choice is used on every later launch and wins over Start enabled.

• Enabling replays the link that opened the game, if it arrived while disabled.
• While disabled, HandleUrl returns false and async calls fail with SdkDisabled.

IsEnabled

public static bool IsEnabled { get; }

true when the native SDK has started and is enabled. Always false in the Editor.

Deep links

See Deep linking.

DeeplinkReceived

public static event Action<GrovsDeeplink> DeeplinkReceived

Fires for each opened link: universal links and App Links, the URI scheme, deferred deep links, Grovs push taps and HandleUrl.

• Links that arrive while there's no subscriber are kept, up to 20 (the oldest is dropped), and delivered in order to the first subscriber.
• An exception thrown by a handler is logged and doesn't stop the other handlers.

LastDeeplink

public static GrovsDeeplink LastDeeplink { get; }

The most recent link, or null.

HandleUrl

public static bool HandleUrl(string url)

Handles a link tapped inside the game. The result arrives in DeeplinkReceived.

• Throws ArgumentNullException for null, and ArgumentException when the URL isn't absolute with a scheme and a host.
• Returns false while Grovs is disabled.

Links

See Link creation.

GenerateLinkAsync

public static Task<string> GenerateLinkAsync(GenerateLinkOptions options)

Creates a smart link and returns its URL. null options create a link with no metadata.

• Throws ArgumentException when options.Data holds a value that isn't JSON-serializable.
• Fails with LinkGenerationFailed, SdkDisabled, SdkNotInitialized or UnsupportedPlatform.
• While authentication is retrying, iOS waits and Android fails right away.

GenerateLink

public static void GenerateLink(GenerateLinkOptions options, Action<string, GrovsError> callback)

Callback version of GenerateLinkAsync. The callback gets the link, or null and the error.

GetLinkDetailsAsync

public static Task<IReadOnlyDictionary<string, object>> GetLinkDetailsAsync(string path)

Returns the details the backend has for a link path, for example "/abc". Throws ArgumentNullException for null. Fails with LinkDetailsFailed when there are none.

GetLinkDetails

public static void GetLinkDetails(string path, Action<IReadOnlyDictionary<string, object>, GrovsError> callback)

Callback version of GetLinkDetailsAsync.

Users

SetUserIdentifier

public static void SetUserIdentifier(string id)

Your ID for the player. null clears it.

SetUserAttributes

public static void SetUserAttributes(IDictionary<string, object> attrs)

Attributes of the player. Values must be JSON-serializable, otherwise it throws ArgumentException. null entries are dropped.

Events

See Events & screen tracking.

Track

public static void Track(string name, IDictionary<string, object> properties = null, IList<string> tags = null)

Tracks a custom event.

• Throws ArgumentNullException for a null name, and ArgumentException for a property value that isn't JSON-serializable.
• Logs a warning, and still sends the event, for an empty or reserved name, properties over 8192 bytes of JSON, more than 20 tags, or a tag over 255 characters.

TrackScreenView

public static void TrackScreenView(string screenName, IDictionary<string, object> properties = null)

Tracks a screen view. Throws ArgumentNullException for a null name. Native automatic screen tracking is off, so this and Track scenes are the only sources of screen views.

SetGlobalTags

public static void SetGlobalTags(IList<string> tags)

Tags added to every event. null clears them.

SetScreenAliases

public static void SetScreenAliases(IDictionary<string, string> aliases)

Maps tracked screen names to the names shown in the dashboard, for example { "MainMenu", "Home" }. null sends an empty map.

Revenue

See Revenue.

LogInAppPurchaseAsync

public static Task<bool> LogInAppPurchaseAsync(string storeTransaction)

Logs a store purchase.

Throws ArgumentException for an empty or null string.

LogCustomPurchaseAsync

public static Task<bool> LogCustomPurchaseAsync(
    GrovsTransactionType type,
    int priceInCents,
    string currency,
    string productId,
    DateTime? date = null)

Logs a purchase outside the stores. date is the transaction date, null for now. Throws ArgumentNullException for a null currency or product ID. On Android the result is true once the call is handed over.

GrovsUnityIAP

public static class GrovsUnityIAP

In the GrovsSDK.IAP assembly, which compiles only when com.unity.purchasing 4.0 or newer is installed. Supports the Apple App Store, the Mac App Store and Google Play.

LogPurchaseAsync

public static Task<bool> LogPurchaseAsync(Product product)

Logs a Unity IAP 4 or 5 Product from its receipt. Throws ArgumentNullException for null. Resolves false, with a warning, when the receipt can't be used.

LogOrderAsync

public static Task<bool> LogOrderAsync(Order order)

Logs a Unity IAP 5 Order. Needs com.unity.purchasing 5.0 or newer. Throws ArgumentNullException for null. Resolves false, with a warning, when the order has no info or the receipt can't be used. On iOS, call it before confirming a consumable.

Push

See Push notifications.

SetPushToken

public static void SetPushToken(string token)

Only needed when the game gets push tokens itself and Grovs can't see them. Grovs reads the APNs token from Unity on iOS and the FCM token from Firebase on Android.

IsGrovsNotification

public static bool IsGrovsNotification(IDictionary<string, string> data)

true when Grovs sent the notification with this data. false for null.

HandleNotificationOpen

public static bool HandleNotificationOpen(IDictionary<string, object> data)

Handles a tap on a Grovs notification that reached your code another way. Reports the open and delivers the link to DeeplinkReceived. Returns false for null or when the native SDK hasn't started. Values must be JSON-serializable.

In-app messages

See In-app messages.

InAppMessageEvent

public static event Action<InAppMessageEvent> InAppMessageEvent

Fires when a message is shown, clicked, dismissed, answered or fails. See InAppMessageEvent for the fields.

ShouldShowInAppMessage

public static Func<string, bool> ShouldShowInAppMessage { get; set; }

Called with the campaign ID before a message shows. Return false to hold it back. null (the default) shows every message.

• Runs synchronously on a native thread: the main thread on iOS, the Android UI thread (not Unity's) on Android. Keep it fast and don't call Unity APIs from it.
• If it throws, the exception is logged and the message shows.

PauseInAppMessages

public static void PauseInAppMessages()

Holds messages back. The newest highest priority match waits.

ResumeInAppMessages

public static void ResumeInAppMessages()

Lets messages show again, starting with the one that waited, if it still qualifies.

DiscardInAppMessages

public static void DiscardInAppMessages(bool dismissCurrent = false)

Drops the waiting message. With dismissCurrent: true, also closes the one on screen.

SetInAppExcludedScreens

public static void SetInAppExcludedScreens(IList<string> screens)

No message shows on these screens. Names match tracked screen names. null clears the list.

SetInAppDebugLogging

public static void SetInAppDebugLogging(bool enabled)

Logs each campaign considered for an event and why it was skipped. Set the log level to Info to see it.

Types

GrovsDeeplink

public sealed class GrovsDeeplink
{
    public string Link;
    public IReadOnlyDictionary<string, object> Data;
    public GrovsTracking Tracking;
    public bool FromPush;
    public string RawJson;
}

GrovsTracking

public sealed class GrovsTracking
{
    public string Campaign;
    public string Source;
    public string Medium;
}

GenerateLinkOptions

public sealed class GenerateLinkOptions
{
    public string Title, Subtitle, ImageUrl;
    public IDictionary<string, object> Data;
    public IList<string> Tags;
    public GrovsRedirect IosRedirect, AndroidRedirect, DesktopRedirect;
    public bool? ShowPreviewIos, ShowPreviewAndroid;
    public bool? CopyToClipboardIos, CopyToClipboardAndroid;
    public string TrackingCampaign, TrackingSource, TrackingMedium;
}

All fields are optional. null fields are left out and use the dashboard or project defaults. See Options.

GrovsRedirect

public sealed class GrovsRedirect
{
    public string Url;
    public bool OpenAppIfInstalled = true;
}

A redirect without a Url is ignored.

InAppMessageEvent (type)

public sealed class InAppMessageEvent
{
    public InAppEventType Type;
    public string CampaignId;
    public string ButtonId;
    public IReadOnlyDictionary<string, object> Payload;
    public string DismissReason;
    public object AnswerValue;
    public string Comment;
    public string FailureMessage;
}

InAppEventType

public enum InAppEventType { Shown, Clicked, Dismissed, Answered, Failed }

GrovsError

public sealed class GrovsError
{
    public GrovsErrorCode Code;
    public string Message;
}

ToString() returns "Code: Message".

GrovsErrorCode

public enum GrovsErrorCode
{
    AuthenticationFailed,
    NetworkRequestFailed,
    EventDispatchFailed,
    LinkGenerationFailed,
    InAppDisplayFailed,
    LinkDetailsFailed,
    NotificationsError,
    SdkNotInitialized,
    SdkDisabled,
    InvalidArgument,
    UnsupportedPlatform,
    Unknown
}

GrovsException

public sealed class GrovsException : Exception
{
    public GrovsError Error;
}

Thrown when an awaited Grovs task fails. Message is the error's message.

GrovsLogLevel

public enum GrovsLogLevel { Info = 0, Warn = 1, Error = 2 }

GrovsTransactionType

public enum GrovsTransactionType { Buy = 0, Cancel = 1, Refund = 2 }

Editor

GrovsSettings

namespace GrovsSDK.Editor
{
    public class GrovsSettings : ScriptableObject
    {
        public const string AssetPath = "Assets/Grovs/GrovsSettings.asset";
        public static GrovsSettings LoadOrCreate();
    }
}

The asset behind Edit → Project Settings → Grovs. It's read by the build only, never at runtime. Its fields match the settings table: apiKey, environment (GrovsEnvironment: TestForDevelopmentBuilds, Production, Test), baseUrl, startEnabled, clipboardDomains, uriScheme, linkDomains, pushEnabled, androidPushMode (GrovsAndroidPushMode: Auto, FirebaseUnity, Standalone), iosOwnNotificationDelegate, androidSmallIcon, googleServicesJsonPath, trackScenes and logLevel.

LoadOrCreate() returns the asset, creating it at AssetPath if it's missing. Use it from build scripts to set values per build, for example the API key from a CI secret. Restore the old values after the build so real keys aren't saved to the asset.

Grovs → Simulate Deep Link opens a window that fires DeeplinkReceived in Play Mode. See Testing links in the Editor.