Developer's Guide to Installing the Pendo Xamarin Forms 5 SDK

 

The Xamarin Forms 5 Pendo SDK is intended to be installed in the Xamarin shared project space, allowing the SDK to run simultaneously for both iOS and Android.

If you are not using Xamarin Forms 5+, or you have previously set up the Pendo SDK independently in the iOS Xamarin or Android Xamarin spaces, follow the articles Installing the Pendo Xamarin Android SDK and Installing the Pendo Xamarin iOS SDK

 

Install instructions 

  1. Select Settings > Subscription Settings > Add Another App and select the Xamarin Forms 5+ app type.

    Xamarin_forms5%2B_app.png

  2. Note that in Pendo, two applications are created under the 'Subscription Settings' page (one for Android and one for iOS).

    xamarinforms_ios_android.png

  3. Select either app and select Continue to installation.

 

Pendo Setup and Initialization

The SDK initialization has three parts, importing the SDK, setting up the SDK to communicate with Pendo's servers, and starting a recording of a session. Setting up the communication with Pendo's server should be conducted once the application launches. Once connected, you can start the session recordings.

Pendo must be initialized to identify the user, begin data collection, and display guide content. The SDK can be initialized when the visitor is authenticated and metadata is known or with an anonymous visitor. Recording a session can be conducted when the application starts, later when the visitor is identified, or at any time you need to identify the current visitor and start a new session.

Identified visitors use a defined schema to create visitor and account objects with associated metadata in Pendo. Refer to the article on Visitor and Account Metadata for additional information on how this data is defined and used in Pendo. Passingnull or "" as the visitorId generate an anonymous visitor ID.

  • visitorId - String containing a unique User ID (e.g. "user-SFGH-56gh"), this ID should match the visitor ID for any other Pendo web or mobile apps
  • accountId - String containing unique Account ID, affiliation of the visitor to a specific company or group (e.g. Acme Inc), this ID should match the visitor ID for any other Pendo web or mobile apps
  • visitorData - Visitor metadata (e.g email, phone, country, etc.)
  • accountData - Account metadata (e.g tier, level, ARR, etc)

Step 1: Install Pendo SDK

  1. In Visual Studio Solution Explorer, right-click on your project, then select "Add" - > "Add NuGet Packages…".
  2. Search for PendoSDKXamarin with the latest version.
  3. Press Add Package.

 

Step 2: Pendo SDK integration

Open the shared application App.xaml.cs and add the following under 'using':

Note: PendoSDKXamarin plugin requires TargetFrameworkVersion v12.0.

...
 using PendoSDKXamarin;
 ...

 namespace ExampleApp
 {
   public partial class App : Application
   {
       ....
       private static IPendoInterface Pendo = DependencyService.Get<IPendoInterface>();
       ....    

 

In the protected override void OnStart() method, add the following code:

protected override void OnStart()
{
   string appKey = "putYourAppKeyHere"
   Pendo.Setup(appKey);
   ...

 

Start the visitor's Session in the page where your visitor is being identified (e.g. login, register, etc.).

...
 using PendoSDKXamarin;
 ...

 namespace ExampleApp
 {
   class ExampleLoginClass
   {
   ...
   private static IPendoInterface Pendo = DependencyService.Get<IPendoInterface>();
   ...
   public void LogginCallBackExampleMethod()
   {
       ....
       var visitorId = "VISITOR-UNIQUE-ID";
       var accountId = "ACCOUNT-UNIQUE-ID";

       var visitorData = new Dictionary<string, object>
       {
           { "age", 27 },
           { "country", "USA" }
       };

       var accountData = new Dictionary<string, object>
       {
           { "Tier", 1 },
           { "Size", "Enterprise" }
       };

       Pendo.StartSession(visitorId, accountId, visitorData, accountData);
       ...
   }
   ...

visitorId: a user identifier (e.g. John Smith)
visitorData: the user metadata (e.g. email, phone, country, etc.)
accountId: an affiliation of the user to a specific company or group (e.g. Acme inc.)
accountData: the account metadata (e.g. tier, level, ARR, etc.)

This code ends the previous mobile session (if applicable), starts a new mobile session and retrieves all guides based on the provided information.

Tip: Passingnull or "" as the visitorId generates an anonymous visitor id.

 

Step 3. Mobile device connectivity for tagging and testing

These steps enable page tagging and guide testing capabilities.

 

iOS

  1. Add Pendo URL Scheme to info.plist file:
    Under the iOS App Target > open info.plist > if URL Types doesn't exist, click on 'Add new entry' and name it 'URL types', for the type choose 'Array'. Create a new URL by clicking the + button. Under the new created Dictionary, change 'Document role' to 'URL Schemes' with type 'Array'. Expand 'URL Schemes' and add the pendo-2461ef69 under the 'Value'. Under the created Dictionary in the previous step, add new entry with the name 'URL Identifier', type 'string' and set a name of your preference under its 'Value'.
  2. Add or modify the function OpenURL:
    Open AppDelegate.cs file and add the following code under OpenUrl method:
    public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
    {
        if (url.Scheme.Contains("pendo"))
        {
            PendoForms.PendoManager.InitWithUrl(url.AbsoluteString);
            return true;
        }
        return true;
    }

 

Android

Add the following activity to the application AndroidManifest.xml in the tag:

<activity android:name="sdk.pendo.io.activities.PendoGateActivity" android:launchMode="singleInstance" android:exported="true">
 <intent-filter>
   <action android:name="android.intent.action.VIEW"/>
   <category android:name="android.intent.category.DEFAULT"/>
   <category android:name="android.intent.category.BROWSABLE"/>
   <data android:scheme="putYourSchemeHere"/>
 </intent-filter>
</activity

 

Step 4: Verify installation

  1. Using Visual Studio: Run the app and search in the device log for:
    Pendo SDK was successfully integrated and connected to the server. 
  2. Click to go through a verification process for the SDK integration.
  3. Confirm that you can see your app under subscription settings as Integrated.

 

Troubleshooting Xamarin Forms 5 Installation

If you previously installed the Xamarin SDK with an iOS and Android platform-specific application key, and you now want to install the new shared app, you should remove the previous installation code from the iOS Xamarin Project and Android Xamarin Project spaces and follow the instructions above. Note that the Xamarin shared project installation instructions above expect a single application key, so, when applying the instructions you should adjust the code to combine the two iOS and Android distinct application keys that you were previously using in your project as follows:

private const string KeyIOS = PENDO_IOS_KEY;
private const string KeyAndroid = PENDO_ANDROID_KEY;

private string Key() 
{
    string key = null;

    if (Device.RuntimePlatform == Device.iOS)
    {
        key = KeyIOS;
    }
    else if(Device.RuntimePlatform == Device.Android)
    {
        key = KeyAndroid;
    }

    return key;
}

Note: Our Shared Plugin depends on pendo-sdk-android-xamarin-forms which has its own dependencies. Please take a look at the pendo-sdk-android-xamarin-forms dependencies and make sure they are all updated.

Upgrade Xamarin Forms 5 to MAUI

To upgrade the Xamarin Forms 5 app to MAUI:

  1. In the file browser in Visual Studio, right-click the Dependencies folder and select Manage Nuget packages...
  2. Search for "pendo-maui" and in the bottom, right corner, select the latest version.
  3. Select Add Package.

Once the package is installed, make the following changes:

  • Change everywhere "using PendoSDKXamarin;" is used to "using PendoMAUIPlugin;"
  • Remove the lines containing the Pendo object initialization as follows:
    • "private static IPendoInterface Pendo = DependencyService.Get<IPendoInterface>();" and instead add: "PendoInterface Pendo = new PendoInterface();"
  • For iOS, under "AppDelegate.cs", change "using PendoForms;" to "using PendoMaui;"

 

Known limitation

The Drawer page doesn’t trigger a screenChangedevent, so it is not possible to collect page analytics on this page. In addition, tooltips on features, and page activation for guides are not shown because they are not scanned on the Drawer page.

To collect correct feature analytics on the Drawer page, you must tag each feature on the page as app-wide.