Android Integration Guide

Registering/Unregistering the Activity Callback to the SDK

With the re-write of the SDK, we leveraged a modern architecture using modules. This allows for greater flexibility in where the engage method can be called from.

The Alchemer Mobile SDK now needs to register the Activity to the SDK in order to show our Interactions in your application.

This will need to be done for every Activity within your application.

This is a 4 step process:

1. Extend the ApptentiveActivityInfo interface to your Activity
2. Override the getApptentiveActivityInfo function
   1. You will just return this (the Activity)
3. Register the callback with the Apptentive SDK using the registerApptentiveActivityInfoCallback function within your onResume function (after the super)
4. (Optional) Unregister the callback using unregisterApptentiveActivityInfoCallback function within your onPause function (before the super)

Kotlin:

class MainActivity : AppCompatActivity(), ApptentiveActivityInfo {
    override fun onResume() {
        super.onResume()
        Apptentive.registerApptentiveActivityInfoCallback(this)
    }

    override fun getApptentiveActivityInfo(): Activity {
        return this
    }

    override fun onPause() {
        //Optional from 6.0.1
        Apptentive.unregisterApptentiveActivityInfoCallback(this)
        super.onPause()
    }
}

Java:

public class MainActivity extends AppCompatActivity implements ApptentiveActivityInfo {
    @Override
    protected void onResume() {
        super.onResume();
        Apptentive.registerApptentiveActivityInfoCallback(this);
    }

    @NonNull
    @Override
    public Activity getApptentiveActivityInfo() {
        return this;
    }
  
    @Override
    protected void onPause() {
        //Optional from 6.0.1
        Apptentive.unregisterApptentiveActivityInfoCallback(this);
        super.onPause();
    }
}

Alchemer Digital Configuration Optional Parameters

The configuration options are enabled with defaults that are production-ready. Check out here for more details.

Migrating from Legacy SDK 5.x to 6.x

Use this migration guide if you are still using Legacy SDKs to make use of Response targeting and extended dev-supported interface customization. Going forward only 6.x+ will get all the new features.

Device Storage Encryption

If your application maintains sensitive user data (account numbers, health information, etc) and you pass it to Mobile SDK (as a custom person/device data) – you may want to enable encrypted device storage.

This can be done when setting the ApptentiveConfiguration.

Kotlin:

val configuration = ApptentiveConfiguration(...)
configuration.shouldEncryptStorage = true
Apptentive.register(this, configuration)

Java:

ApptentiveConfiguration configuration = new ApptentiveConfiguration(...)
configuration.setShouldEncryptStorage(true);
Apptentive.register(this, configuration);

Your app doesn’t need this option if it won’t pass any sensitive information to Alchemer Digital. The Mobile SDK itself does not store any sensitive information (anything an attacker can use to compromise user accounts) unless it is passed to it through custom person/device data.

Styling Alchemer Digital

Alchemer Digital will inherit your app’s styles by default. Check out here to learn what we have added in 6.x and what has changed since 5.x.

Rich content 

Starting from the version 6.6, Prompts (formerly called Notes) can be styled through dashboard. Check out here to learn more.

Note: If a Prompt is customized to include an image via both interface customization and the dashboard, the image added through the dashboard overrides the interface customization setting. 

Local interface customization

If you want to customize more, check this article on our interface customization currently available and how the default interaction UIs look.

Logging

To set the severity of log messages shown in the logs, set the Alchemer Digital LogLevel. The default is set to LogLevel.Info.

Kotlin:

val configuration = ApptentiveConfiguration(...)
configuration.logLevel = LogLevel.DEBUG
Apptentive.register(this, configuration)

Java:

ApptentiveConfiguration configuration = new ApptentiveConfiguration(...)
configuration.setLogLevel(LogLevel.Debug);
Apptentive.register(this, configuration);

Engage Events

You will use these Events later to target Interactions, and to determine whether an Interaction can be shown. You trigger an Event with the engage() method. This will record the Event, and then check to see if any Interactions targeted to that Event are allowed to be displayed, based on the logic you set up in the Alchemer Digital Dashboard.

From 6.0, engage() can be passed with an optional callback method EngagementCallback that accepts EngagementResult as a parameter. EngagementResult helps you understand if the engage call has triggered an interaction or not.

Events can be added almost* anywhere in the App. A few good places would be when an Activity comes to focus, on a button tap or when the App encounters an error.

Kotlin:

override fun onResume() {
   super.onResume()
   /* Engage event when an Activity is foreground */
   Apptentive.engage("my_activity_focused") { result ->
      when (result) {
         is EngagementResult.InteractionShown -> { /* Interaction was shown */ }
         is EngagementResult.InteractionNotShown -> { /* Interaction was NOT shown */ }
         is EngagementResult.Error -> { /* There was an error during evaluation */ } 
         is EngagementResult.Exception -> { /* Something went wrong */ } 
      }
   }
}

private fun setListeners() {
    sendButton.setOnClickListener {
       /* Engage event when a button is tapped */
       Apptentive.engage("send_button_clicked") { result ->
          if (result is EngagementResult.InteractionShown) {
             /* Interaction is shown */
          }
       }
    }
}

private fun processInput() {
   try {
      processUserInput();
   } catch (e Exception) {
     /* Engage event when the app encounters an error */
     Apptentive.engage("exception_processing_user_input")
   }
}

Java:

@Override
protected void onResume() {
   super.onResume();
   /* Engage event when an Activity is foreground */
   Apptentive.engage("my_activity_focused", null, new EngagementCallback()  {
       @Override
       public void onComplete(EngagementResult result) {
           if (result instanceof EngagementResult.InteractionShown) {
               /* Interaction was shown */
            } else if (result instanceof EngagementResult.InteractionNotShown) {
                /* Interaction was NOT shown */
            } else if (result instanceof EngagementResult.Error) { 
                /* There was an error during evaluation */ 
            } else if (result instanceof EngagementResult.Exception) {
                /* Something went wrong */
            }
        }
   });
}

private void setListeners() {
   /* Engage event when a button is tapped */
   sendButton.setOnClickListener(new View.OnClickListener() {
      public void onClick(View view) {
         Apptentive.engage("send_button_clicked");
      }
    });
}

private void processData() {
   try {
     processUserInput();
   } catch (Exception e) {
     Log.e(TAG, e);
     /* Engage event when the app encounters an error */
     Apptentive.engage("exception_processing_user_input");
   }
}

You can add an Event almost anywhere in your app, just remember that if you want to show an Interaction at that Event, it needs to be a place where launching an Activity (Survey and Message Center) or a Dialog (Love Dialog & Prompts) will not cause a problem in your app.

Event Names

Our web dashboard works best for up to several dozen unique event names. It does not work well if you auto-generate thousands of unique event names. If you plan to target users based on viewing a piece of content out of a collection of hundreds or thousands (say, SKUs in an online retail app), do not create event names for each piece of content. Instead, you can use Custom Person Data for items viewed.

For example, you could set a key viewed_item with a value 123456. You could then target users for whom that key matches.

Event Monitoring

Event monitoring will allow you to listen to and act on specific events from the Mobile SDK.

The SDK will post a EventNotification data class to the eventNotificationObservable Observable from the Apptentive.kt class when an event is engaged.

The EventInteraction data class returns a name, vendor, interaction, and interactionId

• name the name of the event that was passed into the engage method.
• vendor the organization that created the event. Internal Mobile SDK-engaged events will have “com.apptentive” and app-engaged events will have “local”.
• interaction the name of the interaction that the event was engaged from (see table below). “app” if not engaged from an interaction.
• interactionId the id of the interaction that the event was engaged from. null if not engaged from an interaction.

Kotlin:

Apptentive.eventNotificationObservable.observe { notification ->
    val name = notification?.name
    val vendor = notification?.vendor
    val interaction = notification?.interaction
    val interactionId = notification?.interactionId?.let { id -> "\"$id\"" } ?: "`null`"

    val notificationText = "Name: \"$name\". Vendor: \"$vendor\". " +
                    "Interaction: \"$interaction\". Interaction ID: $interactionId"
    Log.d("APPTENTIVE_EVENT", notificationText)

    // Survey interaction handling
    if (interaction == "Survey") {
        when (name) {
            "launch" -> { /* Survey shown */ }
            "submit" -> { /* Survey completed */ }
            "cancel", "cancel_partial" -> { /* Survey closed without completing */ }
        }
    }
}

Java:

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...

    Apptentive.getEventNotificationObservable().observe(this::handleEventNotification);
}

public Unit handleEventNotification(EventNotification notification) {
    String name = notification.getName();
    String vendor = notification.getVendor();
    String interaction = notification.getInteraction();
    String interactionId = notification.getInteractionId() != null ?
            "\"" + notification.getInteractionId() + "\"" : "`null`";

    String notificationText = "Name: \"" + name + "\". Vendor: \"" + vendor + "\". " +
            "Interaction: \"" + interaction + "\". Interaction ID: " + interactionId;
    Log.d("APPTENTIVE_EVENT", notificationText);

    // Survey interaction handling
    if (interaction.equals("Survey")) {
        switch (name) {
            case "launch":
                // Survey shown
                break;
            case "submit":
                // Survey completed
                break;
            case "cancel":
            case "cancel_partial":
                // Survey closed without completing
                break;
        }
    }

    return Unit.INSTANCE;
}

Alchemer Mobile SDK Interaction –> EventNotificationinteraction

Internal events

An incomplete list of internal events that the Mobile SDK engages.