Skip to end of metadata
Go to start of metadata

Getting Started

Accengage SDK allows you to track the execution and display of In-App and to handle Push notifications of your application.

This Xamarin documentation explains the various methods available and how to use them.

In order to understand more deeply the features of the SDK, please refer also to the native iOS and Android documentations.

Plugin Version 1.2.0:

  • Android SDK version 3.8.0
  • iOS SDK version  6.3.0

Integration

Add the Xamarin SDK to your reference

On both project Android/iOS of your own project you will need to add as reference the Accengage Plugin available on NuGet. 

Right click on Reference (on both iOS/Android side) and choose Manage NuGet Package, then search Xamarin.Accengage SDK and add it.

Then we recommend you to create a class in a SharedProject which will allow you to only have one class to handle the majority of methods 

you need to run properly our SDK, on iOS and Android side at the same time, since the SharedProject will search the method and adapt on the

environnement he is in to choose the working one.

Using

Using AccengageSDK at the top of your AppDelegate (iOS) or Activity (And) and any of your class:


Android Integration

Prerequisites

  • Compile using AndroidVersion 6 

To use all the potential of the android SDK, some additionnal integration step needs to be done.

Put our service tag insinde your application tag with the proper senderId, partnerID and privateKey.

AndroidManifest.xml

Inside all your Activities, you will need to  Sub Classing any Activity Type.

Following permissions are required in your manifest :

AndroidManifest.xml

Finally you need to add in your manifest inside the application tag our GCMHandler,

AndroidManifest.xml

A4SProvider,

AndroidManifest.xml

and NotificationActionsReceiver:

AndroidManifest.xml

Plugin

 Prerequisites

 To use all of our plugins you will need to setup your compiled android version to 7 since google play services 9.6.1 used the Android.Support.v4 24+ 

Xamarin.Accengage.Android.Plugin Play Services v1.2.0 :

    This plugin allows the SDK to:

  • Register/Unregister to GCM using GooglePlayServices (official and recommended Google's method)
  • Retrieve and send to Accengage the Google Advertiser ID (IDFA) automatically
  • Geolocation using GooglePlayServices (SDK 3.1.0+). Usefull about power comsumption.
  • Geofencing using GooglePlayServices (SDK 3.1.0+)

    This plugin regroup five plugins which you can import in your project separately in fonction of what you need :

  • Xamarin.Accengage.Android.Plugin Play Services Base v1.2.0
  • Xamarin.Accengage.Android.Plugin Play Services Location v1.2.0
  • Xamarin.Accengage.Android.Plugin Play Services Push v1.2.0
  • Xamarin.Accengage.Android.Plugin Play Services Geofence v1.2.0
  • Xamarin.Accengage.Android.Plugin Play Services AdvertiserId v1.2.0

Xamarin.Accengage.Android.Plugin Beacon v1.2.0

    This plugin allows the SDK to:

  • Listen for Beacons
  • Trigger In-Apps and Local Notifications using Beacons

 

Xamarin.Accengage.Android.Plugin Badger v1.2.0

    This plugin allows the SDK to:

  • Manage badge on all layer

 

iOS Integration

To use all the potential of the iOS SDK, some additionnal integration step needs to be done.

Prerequisites

  • XCode 8
  • iOS 8 and higher.

Configure push notifications

Push notifications allow an app that isn’t running in the foreground to notify the user when it has information for them. Push notifications originate from a notification server that you manage and are pushed to your app on a user’s device by the Apple Push Notification service (APNs).

First, you enable push notifications in the Xamarin project.

After you enable push notifications, generate and export a TLS certificate.

Enable push notifications

Please ensure that in the Entitlements.plist file, your Push Notifications entitlement is checked.

 

Creating and using certificates 

Please follow this Xamarin documentation link to learn how to create a certificate, associate it with a provisioning profile, and then get a Personal Information Exchange certificate.

Configure URL schemes

Creating an URL schemes

Deep Linking is becoming very important, it's a great way to enhance the effectiveness of you app's marketing campaigns.

It will allow you to open a specific view of your app from another app, from a push message, from an in-app message

or even from a website to your app.

To take advantage of it, you must create a custom URL Scheme associated with your application. A URL scheme lets you

communicate with other apps through a protocol that you define. To find out more, check out Apple documentation

To register your URL Scheme:

  1. Open your Info.plist and select the Advanced tab.
  2. Click Add URL Type in the URL Types expander.
  3. In URL Schemes field, enter your_app_url_scheme.
  4. Assign a unique identifier to the scheme to ensure uniqueness and avoid name collisions, so we'll use com.myapp.url for the example. 

To verify that everything works:

  1. Run your app.
  2. Open Safari on the same device.

Type your_app_url_scheme:// in the address bar, then press Go.

Whitelisting URL Schemes

Like ATS, iOS 9 introduces changes that impact URL Scheme management. For more details, you can consult Apple's documentation.

Make sure that your application Info.plist includes the LSApplicationQueriesSchemes set with the Log App's URL scheme.

Configure logging

Configure logging application

Accengage provide an application to help your team to identify for sure their device profile among the others, which is helpful for push notifications tests. It also allows our technical team to properly investigate in case of unexpected behavior. We strongly recommend it.

Note

This configuration is mandatory if Accengage teams need to test the SDK integration.

In order to be able to use our application, you will need to:

  1. add the scheme bma4sreceiver to the schemes whitelist as explained in the previous section.
  2. add a localhost exception to the App Transport Security key in your info.plist.
Enabling console logs

For diagnostic purposes, the library contains an option that turns on logging. These logs allow you to gain more insight on the library's integration and ensure it's working as expected. These logs can also be helpful for support staff who are troubleshooting problems.

Configuration File

First, get an empty configuration file to add to your project from this link.

Drag the AccengageConfig.plist file you just downloaded into the root of your Xamarin iOS project and add it to all targets then complete it with your own partner id and private key.

Right-click the file and set Build Action to BundleRessource.

 

Initialization

Now you're ready to begin implementing. Start the library in your AppDelegate FinishedLaunching method. From version 1.2.0 of the plugin, several ways to manager SDK starting are available depending on whether you need to use features related to GDPR. If you need more details, please refer to iOS native documentation

GDPR management

 If you plan to start the SDK using GDPR related features, data collection is disabled by default. Data collection is mandatory to use most of the SDK features. If you need it, you have to enable it explicitly.

 

Plugin 1.2.0 also brings features related to geolocation optin.

Import natives methods

If a feature is not available in the wrapper, You can directly use the binded sdk as if you coded natively. Use this namespace.

    Push

    Android

    To enable push follow the android documentations.

    Prevent Rich Push Notifications display

    You can prevent the display of any RichPush notification, by calling: 

    To reenable the RichPush Notifications, you can call:

    You can enable/disable RichPush notifications at any time.

     

    iOS

    Registering

    In order to register for user notifications, you can call the registerForUserNotificationsWithOptions() method. This means that you're no longer required to maintain the registration by yourself, just call this method and the library will request notification authorization for you.

    Important

    Your must register for user notifications every time your app is launched.

    Media attachments

    iOS 10 introduces support for rich notifications, it adds the abitity to send push with media attachments such as images, sounds and videos.

    Rich notifications are available on iPhone 5s or later, iPad Pro, iPad Air or later, and iPad mini 2 or later.

    To enable this functionality, you will need to create a Notification Service Extension.

    Important

    Only work with Xamarin.iOS 10.4 and higher.

    1. Once your notification service is created, add the nuget package Xamarin.Accengage.iOS.Extension in extension.
    2. Inherit from ACCNotificationServiceExtension in NotificationService and delete all the code generated by Xamarin.

    It is possible to disable the display of push using :

    InApp

    The Accengage SDK provides you with notifications display without any additional code to write in order to support them.

    It is possible to disable the display of InApp, for example if you are using splashscreen or if you have views in which you don't want them to appear using.

    Tracking

    Events

    To use the additional parameters of the custom events for targeting purposes, they must formatted as a valid json string. Use a timestamp to represent a date.

    If you want to track a specific event :


    Where 1000 is the eventId.

    Analytics

    You can track specific events like “Add to Cart”, “Purchase” and “Lead”. Here is how to use each of these events.

    Lead 

    Add to Cart

    First of all you will need to create an Item using the AccengageItem class.

    Currency should be a valid 3 letters ISO4217 currency (EUR,USD,..) and the 2 last arguments are price and quantity

    Now you just have to add it to the Cart.

    Purchase

    Update Device Info

    You can create a device profile for each device in order to qualify the profile (for example, registering whether the user is opt in for or out of some categories of notifications).

    A device profile is a set of key/value that are uploaded to Accengage server. In order to update information about a device profile, add the following lines to your code:

    Where listUdi is a List<KeyValuePair<string, string>> containign all the informations to update.

    Views

    You can identify each views of your application that the SDK can refer to using.

    where MyView is the name of your view.

    iOS

    This method must take place in the viewDidAppear and is to be used with TrackScreenDismiss in the viewDidDisappear. Look the Documentation.

    DeepLinking

    In the Accengage Interface, you can specify some custom parameters linked to click and/or display actions. The Accengage SDK sends a broadcast each time an item is displayed or clicked on in order to give you back these parameters.

    Here is how to retrieve your custom parameters from any kind of notification.

    Retrieving Inapp/Push custom param

    Android 

    Follow the android documentation available here.

    iOS

    Follow the iOS documentation available here.

     

    Inbox

    The inbox feature was made to display some delayed messages to your users. These messages can be a text, a webpage, a richpush, ... with or without buttons.

    These messages and buttons interact directly with the Accengage SDK.
    You can for instance send a message with an event button, trigger a URL scheme, or display a banner/interstitial when the user opens a message.
    This inbox can be used to store push messages received but not opened by the user.
    Indeed, with this feature, the user can browse all of the messages you sent to him before.
    The inbox can be used as a reminder or as a lite mail client in order to communicate with your clients.

    If you want to use this feature, Accengage servers will send all the messages information to your app, but you will need to handle yourself the display part.

    With Accengage Inbox you can :

    • Obtain messages and display them in your own template
    • Update messages status on Accengage Servers (Read/Unread/Archived)

    You can find a complete example in our sample project.

    After being sure you greatly integrate our sdk with the previous chapter, you can now access to our Inbox Implementation.

    Obtain Messages

    You will need an async callback to be notified when n Inbox is received. Here is an example of how to define it:

    List Messages

    Once you retrieved your AccengageInbox object you can access to AccengageInboxMessage. In this example, we will just display a log with the title of each message:

    The process is asynchronous and the callback order is NOT garanteed.
    Double checking the index provided when a message is received is mandatory to avoid errors in your code.

    Message interactions

    Now that we have downloaded and displayed our messages, we will allow our user to interact with them.

    For example, if you display a message in a list, you may want to provide the user with some interaction if he touches a row.

    You will need to give the message the user interacted with to the SDK.

    According to the message format, the SDK can either start a predefined action or give it back to you to be displayed.

    Once it is loaded you have fully access to all the content of your message.

    Work with Message Buttons

    A message content can have some buttons. Here is an example of how to display and interact with these them.

    Update message status

    You can change the status of a message, here is how to do it:

    Other Methods

    Restricted Network

    You can temporarily restrict the connections in order to tell our SDK to stop flushing network requests.

    Disable Accengage Service

    If a user want to disable all Trackings, and Sdk Services you can use this code.

    • No labels
    Page: Changelog Page: Getting started Page: InApp Page: Inbox Page: Integration Page: Push Page: Tracking