Maui

1. Install the SDK

• Refer to the latest version of the Localytics Maui NuGet package on the NuGet Gallery.
• For Maui single project type, you can install the SDK once for the whole project level, while for multi-project .net types, you need to install the SDK for each platform project.
• Starting from LocalyticsMaui 1.0.8, targeting JDK 17 is required, which isn't downloaded by default for Visual Studio. You can edit the used JDK path from the Visual Studio settings.

2. Package Names

• LocalyticsMaui.iOS - APIs available for use on the iOS platform iOS Localytics Docs
• LocalyticsMaui.Android - APIs available for use on the Android platform Android Localytics Docs
• LocalyticsMaui.Common - class available on both iOS and Android using .net dependencies only. The interfaces are the same across platforms offering similar functionality.

3. Platforms shared code

Add a file to your platforms shared code with the following contents

using LocalyticsMaui.Common;
# if __ANDROID__
using LocalyticsMaui.Android;
# else
using LocalyticsMaui.iOS;
# endif
namespace LocalyticsSample // Your project's namespace
{
public class LocalyticsMaui : LocalyticsSDK, ILocalytics, IPlatform
{
}
}

4. API Summary

APIs follow c# naming conventions and are a translation of the API on the native platform.

Common APIs

5. Dictionaries

Customer Properties Dictionary

This dictionary can be passed to TagCustomerLoggedIn and TagCustomerRegistered API.

6. Events

Events are available as static events in the LocalyticsSDK class in the Localytics.Shared namespace.

Event Args for events common to both Android and iOS share an interface and can be implemented in a Shared PCL project.

IOS Specific Events

Events Args

LocalyticsDidTagEventEventArgs

EventName - string identifying the type of the event.
Attributes - a dictionary identifying the attributes attached to the event
CustomerValue - a nullable double that identifies any provided customer value when tagging the event

LocalyticsSessionDidOpenEventArgs

isFirst - bool identifying if this is the first session
isUpgrade - bool identifying if this session open is following an upgrade
isResume - bool identifying if this is a session that is being resumed.

LocalyticsSessionWillOpenEventArgs

Provides same as properties as LocalyticsSessionDidOpenEventArgs

LocalyticsDidTriggerRegionsEventArgs

Regions providing an array of regions and is of type LLRegion[].
RegionEvent of type LLRegionEvent identifying the trigger event type 'Enter' or 'Exit'.

LocalyticsDidUpdateLocationEventArgs

iOS
Location - CLLocation type which reports the current location.

LocalyticsDidUpdateMonitoredGeofencesEventArgs

AddedRegions and RemovedRegions are additional properties. They are both of type LLRegion[]. AddedRegions provides the array of new regions added. RemovedRegions provides an array of regions that were removed from monitoring.

InAppDidDisplayEventArgs, InAppWillDismissEventArgs, InAppDidDismissEventArgs

These do not define any additional properties other than those in EventArgs and are placeholders for future to minimize signature changes.

DidOptOutEventArgs

The properties are

• Current OptOut status (bool)
• Campaign

7. Delegates

8. Android Versions

9. iOS Versions

• Minimum deployment target is iOS 8.0
• CoreLocation - Required for location services. Requires implementing the request for Location Permissions in the App

10. iOS-Specific Platform Code

In order to use the LocalyticsMaui.iOS API in a source file, you will need to add the namespace LocalyticsMaui.iOS. Before calling anything else on the Localytics API, override the FinishedLaunching in your app delegate to integrate with your Localytics App Key.

Note: it's not recommended to use the AutoIntegrate function as it's not fully supported since .net6

using LocalyticsMaui.iOS;
...
namespace LocalyticsSample;

[Register("AppDelegate")]
public class AppDelegate : MauiUIApplicationDelegate
{
...

public override bool FinishedLaunching(UIApplication uiApplication, NSDictionary launchOptions)
{
...
// Localytics Integrate
Localytics.LoggingEnabled = true;
Localytics.Integrate("b70c948d304fc756d8b6e63-ecd3437a-a073-11e6-c6e3-008d99911bee", launchOptions ?? new
NSDictionary());

// Register for remote notifications
var pushSettings = UIUserNotificationSettings.GetSettingsForTypes(
UIUserNotificationType.Alert | UIUserNotificationType.Badge | UIUserNotificationType.Sound,
new NSSet());

UIApplication.SharedApplication.RegisterUserNotificationSettings(pushSettings);
UIApplication.SharedApplication.RegisterForRemoteNotifications();

return base.FinishedLaunching(uiApplication, launchOptions);
}

protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

Usage

You can use the Localytics API by calling the class methods/accessors of Localytics or LocalyticsSDK. Here's a sample of some of the calls.

LocalyticsSDK localytics = LocalyticsSDK.SharedInstance;
localytics.SetOption("ll_session_timeout_seconds", 10);
localytics.CustomerId = "Sample Customer";

localytics.SetProfileAttribute("Sample Attribute", LocalyticsMaui.Common.XFLLProfileScope.Application, 83);
localytics.AddProfileAttribute("Sample Set", LocalyticsMaui.Common.XFLLProfileScope.Organization, new long[] {
321, 654 });

localytics.TagEvent("Test Event");
localytics.TagScreen("Test Screen");

localytics.Upload();

The above samples only demonstrate the syntax of calling the LocalyticsMaui.iOS API. For more information about how to use Localytics, see iOS Localytics Docs.

Push and In-App Messaging

1. Enable background modes
2. Register for remote notifications

Add the following in your main AppDelegate inside FinishedLaunching where the Integrate call is

if ([application respondsToSelector:@selector(registerUserNotificationSettings:)])
{
UIUserNotificationType types = (UIUserNotificationTypeAlert | UIUserNotificationTypeBadge |
UIUserNotificationTypeSound);
UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:types categories:nil];
[application registerUserNotificationSettings:settings];
[application registerForRemoteNotifications];
}
else
{
[application registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge |
UIRemoteNotificationTypeSound)];
}

3. Receiving Notification in the foreground when the application is in the foreground, DidReceiveRemoteNotification override in the Application is invoked when a notification is received.

NSDictionary apsDict = userInfo.ObjectForKey(new NSString("aps")) as NSDictionary;
// apsDict[new NSString("alert")] returns the message.
// Present the notification using a UIAlert.

WillFinishLaunching or FinishedLaunching override provide the dictionary when the notification was received in the background.

11. Android-Specific Platform Code

In order to use the LocaluticsMaui.Android API in a source file, you will need to add the namespace LocalyticsMaui.Android. Before calling anything else on the Localytics API, you will need:

1. Call one of the Integrate methods Integrate or AutoIntegrate within your custom Application class

using Android.App;
using Android.Runtime;
using LocalyticsMaui.Android;
namespace LocalyticsSample;

[Application]
public class MainApplication : MauiApplication
{
public MainApplication(IntPtr handle, JniHandleOwnership ownership)
: base(handle, ownership)
{
}

override public void OnCreate()
{
base.OnCreate();

#if DEBUG
var localytics = LocalyticsMauiShared.SharedInstance;
localytics.LoggingEnabled = true;
#endif

Localytics.AutoIntegrate(this);

}

protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

2. Modify the AndroidManifest.xml to add App Key, receivers and permissions.

<application android:label="LocalyticsSample" android:icon="@drawable/icon">
    <meta-data android:name="LOCALYTICS_APP_KEY"
        android:value="xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />
    <receiver android:name="com.localytics.android.ReferralReceiver" android:exported="true">
        <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
    </receiver>
</application>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Manifest merging is not supported with Maui. Therefore, all AndroidManifest.xml entries need to be made manually. Follow instructions for manual integration.

3. Configure required parameters using localytics.xml or through setting options. Add a localytics.xml in Resources/values. For a sample refer here.

Usage

You can use the Localytics API by calling the class methods/accessors of Localytics or LocalyticsSDK. Here's a sample of some of the calls.

LocalyticsSDK localytics = LocalyticsSDK.SharedInstance;
localytics.SetOption("ll_session_timeout_seconds", 10);
localytics.CustomerId = "Sample Customer";

localytics.SetProfileAttribute("Sample Attribute", LocalyticsMaui.Common.XFLLProfileScope.Application, 83);
localytics.AddProfileAttribute("Sample Set", LocalyticsMaui.Common.XFLLProfileScope.Organization, new long[] {
321, 654 });

localytics.TagEvent("Test Event");
localytics.TagScreen("Test Screen");

localytics.Upload();

The above samples only demonstrate the syntax of calling the LocalyticsMaui.Android API. For more information about how to use Localytics, see Android Localytics Docs.

Push and In-App Messaging

1. Check for Play Services Availability as described in FCM Notifications Walkthrough.
2. The Localytics Native SDK Push Integration can be used to integrate push.
3. Maui has limited support for manifest merging. The changes are best done directly in AndoidManifest.xml.