What you will learn

This tutorial will teach you how to create an in-app action associated to a specific technology.

Prerequisites - What you need to get started

  • Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
  • A zone, which has been configured on your herow account.
  • An Android Device, with Bluetooth 4.0 and Android 4.0 and above, to be able to interact with BLE beacons.
  • The Android Studio application, which you can download from the Android Developers website.
  • You must have completed the 5 minutes QuickStart Tutorial.

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/Connecthings/sdk-tutorial.git
  • Open the android>zone>3-InApp-Action>Starter project with Android Studio

Step 2: Configure your SDK

  • Open the ApplicationNotification class
  • Configure the SDK with:
    • the appropriate Herow Environment ( PREPROD / PROD )
    • your SDK credentials (your login, password, and company details from Connecthings)
HerowInitializer.getInstance()
				.initInstance(this)
				.initUrlType(UrlType.PRE_PROD / UrlType.PROD)
				.initUser("YOUR_USER",  "YOUR_PWD")
				.initCompany("YOUR_COMPANY_KEY")
				.synchronize();

If you need more informations, have a look to the 5 minutes quickstart tutorial

Step 3: Create your first InApp-Action

  • Open the ActivityMain

  • Implement the InAppActionListener interface

public class ActivityMain extends AppCompatActivity implements View.OnClickListener, InAppActionListener<HerowPlaceInAppAction> {
  • Register the InAppActionListener on the onResume method
@Override
protected void onResume() {
    super.onResume();
    HerowDetectionManager.getInstance().registerInAppActionListener(this);
}
  • Unregister the InAppActionListener on the onPause method
@Override
protected void onPause() {
    super.onPause();
    HerowDetectionManager.getInstance().unregisterInAppActionListener();
}
  • Implement the following abstract methods to detect nearby zones:
@Override
public boolean createInAppAction(HerowPlaceInAppAction placeInAppAction, InAppActionStatusManagerListener inAppActionStatusManagerListener) {

}

@Override
public boolean removeInAppAction(HerowPlaceInAppAction placeInAppAction, InAppActionRemoveStatus inAppActionRemoveStatus) {

}

Note 1:

These callback methods allow you to manage the in-app action lifecycle:

  • createInAppAction: to be notified to create an in-app action. When a zone is detected, our SDK checks that it matches the conditions configured on Herow before allowing the in-app action creation process
  • removeInAppAction: to be notified to remove an in-app action. When a zone is no longer detected, or when it no longer matches the conditions configured on Herow, our SDK proceeds with the in-app action deletion process

Note 2:

The 3 methods above contain the following parameters:

  • PlaceInAppAction: all Herow data associated with a specific technology
  • InAppActionStatusManagerListener: this interface gives you the possibility to declare an in-app action as done
  • InAppActionRemoveStatus: indicates the reason for an in-app action removal
    • PLACE_EXIT: removal due to the exit of a zone's region
    • CONDITION_INVALID: removal due to invalid conditions

Step 4: Generate an InApp-Action

Determine the tag associated with your InApp-Action

Use the placeInAppAction.getTag() method to determine the tag.

This method returns the value defined in the tag field on Herow.

You can set up any value you want on Herow if your application is able to handle this tag.

For instance, if the tag parameter is configured as restaurant on Herow, then the developer needs to code a related view shown when an in-app action is triggered.

@Override
public boolean createInAppAction(HerowPlaceInAppAction placeInAppAction, InAppActionStatusManagerListener inAppActionStatusManagerListener) {
    if (placeInAppAction.getTag().equals("restaurant")) {
      //Show a dedicated view when a user is in a restaurant
      textViewInAppAction.setText(placeInAppAction.getTag());
      btnMore.setVisibility(View.VISIBLE);
    }
    return true;
}
  • Complete the createInAppAction method to anticipate other cases: e.g. default action when the type of action associated with the zone is not recognized
@Override
public boolean createInAppAction(HerowPlaceInAppAction placeInAppAction, InAppActionStatusManagerListener inAppActionStatusManagerListener) {
    currentPlaceInAppAction = placeInAppAction;
    if (placeInAppAction.getTag().equals("restaurant")) {
        textViewInAppAction.setText(placeInAppAction.getTag());
        btnMore.setVisibility(View.VISIBLE);
        return true;
    }
    textViewInAppAction.setText("No POPUP action for zone");
    btnMore.setVisibility(View.GONE);
    return false;
}
  • Implement the removeInAppAction method.
    • If you want to avoid deleting the zone's action when this method is called, make it return false; otherwise, the SDK will automatically flag the zone with actionStatus = InAppActionActionStatus.DONE
@Override
public boolean removeInAppAction(HerowPlaceInAppAction placeInAppAction, InAppActionRemoveStatus inAppActionRemoveStatus) {
    textViewInAppAction.setText("Remove in-app action");
    btnMore.setVisibility(View.GONE);
    return true;
}

Keep in mind when using the default in-app action behavior

To generate the createInAppAction callback

  1. Your zone must be registered on the Herow platform and have associated content.
  2. If an in-app action has already been triggered on a device with the same zone the app must remain within range of the zone for at least 60 seconds, or the device must exit and re-enter the engagement zone's range, for the zone's flag to be reset to readyForAction

To generate the removeInAppAction local in-app action callback

  1. You must have received the createInAppAction callback
  2. The createInAppAction method must have been processed successfully and have returned true
  3. Your zone must no longer be detected

Step 5: Start testing

  1. Configure a in-Action tag compaign on the Herow Platform

  2. From Android Studio, launch the installation process of the application you have just built on your mobile phone.

  3. Activate your zone and put your device in its correct action range (as defined in Herow)

  4. Wait for a few seconds

  5. The tag of the in-app action appears, as defined in Herow, along with a button and the following text: Click to get more information.