This is a reference guide for all Xamarin SDK requirements, known limitations, API reference, and performance impact information.

The Xamarin SDKs are distributed through NuGet.

Requirements + Known Limitations

See Android SDK Reference and Swift and UIKit SDK Reference for platform-specific version support and limitations.
The SDKs target Android and iOS implementations of Xamarin.
The SDKs have only been tested using msbuild and Visual Studio on macOS hardware.
The iOS SDK includes a build step to install two XCFrameworks into the app and needs to be included in the app project even if referenced in other library projects.

API Reference

`HeapInc.Analytics.Android.Implementation`

This class, part of the HeapInc.Analytics.Android package, provides the Heap Android Core SDK bindings and is used for initializing Heap and setting the log level.

`StartRecording (Context context, string environmentId, HeapOptions options = default)`

Description
Initializes the Heap SDK and enables Heap to start recording data.

Parameters

context: The non-null application or activity Context used to initialize Heap SDK components.
envId: The non-null string environment ID to which data should be attributed.
options (optional): The HeapOptions object with installation-specific configuration options.

`SetLogLevel (HeapLogLevel logLevel)`

Sets the current HeapLogLevel for Heap SDK logs. By default, the Heap SDK will print messages at the HeapLogLevel.Info level. This includes any messages that might be helpful in a production environment as well as any critical errors or warnings from the HeapLogLevel.Error and HeapLogLevel.Warn log levels.

Parameters

logLevel: The desired HeapLogLevel of messages to be printed.

`HeapInc.Analytics.iOS.Implementation`

This class, part of the HeapInc.Analytics.iOS package, provides the Heap Android Core SDK bindings and is used for initializing Heap and setting the log level.

`StartRecording (string environmentId, HeapOptions options = default)`

Description
Initializes the Heap SDK and enables Heap to start recording data.

Parameters

envId: The non-null string environment ID to which data should be attributed.
options (optional): The HeapOptions object with installation-specific configuration options.

`SetLogLevel (HeapLogLevel logLevel)`

Parameters

logLevel: The desired HeapLogLevel of messages to be printed.

`HeapInc.Analytics.Heap`

The publicly-facing API for the Heap Xamarin SDK.

Note: All members are static.

`StopRecording ()`

Description
Shuts down the Heap SDK and prevents any further data collection.

Examples

Heap.StopRecording()

`Track (string eventName, Dictionary<string, string> properties = default)`

Description
Creates an event message to be tracked and sent to the Heap API.

Parameters

event: The string name of the event.
properties (optional): The Dictionary<string, string> of properties to associate with the event.

Examples

// Without properties
Heap.Track("Added to cart")

// With properties
Heap.Track("Added to cart", new Dictionary<string, string>
{
  { "item-sku", Item.Sku },
  { "quantity", ItemCount.ToString() },
});

`Identify (string identity)`

Description
Assigns an identity to be associated with the current user ID, used for combining users across multiple implementations.

If the identity is already set and different from the past identity, this will have the effect of resetting the user ID and session while setting the identity.

Parameters

identity: The string value representing the identity to associate with events. This should uniquely identify the person using the app and never a hard-coded value.

Examples
In this example, the app has a method UserAuthenticated which is called when the user logs into the app.

void UserAuthenticated(AppUser user)
{
  ...
  Heap.Identify(user.Identity);
}

`ResetIdentity ()`

Description
Resets the state for a user that was previously identified with Identify, creating a new user and session while clearing event properties. If the user was not previously identified, this method has no effect.

Examples
In this example, the app has a method UserLoggedOut which is called when the user logs out of the app.

void UserLoggedOut()
{
  ...
  Heap.ResetIdentity()
}

`AddUserProperties (Dictionary<string, string> properties)`

Description
Add a collection of properties to be associated with the current user.

Parameters

properties: The Dictionary<string, string> of properties to associate with the current user.

Examples
In this example, the app has a method UserAuthenticated which is called when the user logs into the app.

void UserAuthenticated(AppUser user)
{
  ...
  Heap.AddUserProperties(new Dictionary<string, string>
  {
    { "membership_tier", user.MembershipTier },
    { "team_name", user.Team.Name },
  });
}

`AddEventProperties (Dictionary<string, string> properties)`

Description
Add a collection of properties to be associated with all future events from the current user.

Parameters

event: The string name of the event.
properties: The Dictionary<string, string> of properties to associate with future events.

Examples
In this example, the app has a method ContentLoaded which is called when a view controller loads data and we want to group future events based on the hero banner that was displayed.

void ContentLoaded(HomeScreenContent content)
{
  ...
  
  var heroName = content.Hero?.Name;
  if (heroName is not null)
  {
    Heap.AddEventProperties(new Dictionary<string, string>
    {
      { "home_screen_hero", heroName },
    });
  }
}

`RemoveEventProperty (string name)`

Description
Removes a single event-wide property that was previously added with AddEventProperties.

Parameters

name: The string name of the property.

Examples
In this example, we want to track a property on all events while a view controller is on screen:

protected override void OnStart()
{
  base.OnStart();
  Heap.AddEventProperties(new Dictionary<string, string>
  {
    { "chat_popup_is_visible", "true" },
  });
}

protected override void OnStop()
{
  base.OnStop();
  Heap.RemoveEventProperty("chat_popup_is_visible")
}

`ClearEventProperties ()`

Description
Removes all event-wide properties that were previously added with AddEventProperties.

Examples
In this example, the app has a method CheckoutComplete which is called when the finishes a purchase.

func CheckoutComplete() {
  ...
  Heap.ClearEventProperties()
}

`string? UserId { get }`

Description
Returns the current user ID if Heap is recording, otherwise null.

Return Value
The current Heap-generated user ID used for tracking events, or null if Heap is not recording.

Examples

var heapUserId = Heap.UserId

`string? Identity { get }`

Description
Returns the identity if Heap is recording and the user has been identified, otherwise null.

Return Value
The value that was provided to Identify for the current user, or null if Heap is not recording or Identify has not been called.

Examples

var heapIdentity = Heap.Identity;

`string? SessionId { get }`

Description
Returns the current session ID if Heap is recording and the session has not expired, otherwise null.

This method is useful for reading the current state for purposes such as logging. If you are using the session ID for server-side events, it is recommended that you use FetchSessionId(), which will create a new session if needed.

Return Value
The current Heap-generated session ID, or null if Heap is not recording.

Examples

var heapSessionId = Heap.SessionId;

`string? FetchSessionId ()`

Description
Returns the current session ID if Heap is recording, otherwise null.

If the previous session has expired, this will start a new session.

Return Value
The current Heap-generated session ID, or null if Heap is not recording.

Examples

var heapSessionId = Heap.FetchSessionId();

Performance Impact FAQ

The Xamarin SDKs install a small DLL in addition to the native SDKs.

See Android SDK Reference and Swift and UIKit SDK Reference for platform-specific performance information.