169237837 info about new and updated features (#9)

* Create pending_transaction_listener.html

* Update ussd.md

* More details info about different action types

* Add more customization options

* Add info about running 2 sessions

Author: davkutalek

_includes/pending_transaction_listener.html

@@ -0,0 +1,13 @@
+<figure>
+	<pre><code class="java" data-lang="java">private void callHover() {
+		LocalBroadcastManager.getInstance(context).registerReceiver(pendingTransactionReceiver, new IntentFilter("PENDING_TRANSACTION_CREATED"));
+        startActivityForResult(createHoverIntent(), 0);
+	}
+	private final BroadcastReceiver pendingTransactionReceiver = new BroadcastReceiver() {
+		@Override
+		public void onReceive(final Context context, final Intent i) {
+			Log.i(TAG, "Recieved pending transaction created broadcast");
+            Log.i(TAG, "uuid: " + i.getStringExtra("uuid");
+		}
+	};</code></pre>
+</figure>

actions.md

@@ -34,15 +34,15 @@ Choose the **type** of menu that you are integrating. There are four types:
 
 2.  ###### SIM Toolkit
 
-    A SIM Toolkit (STK) based menu. Primarily for Safaricom MPESA in Kenya, but there are others.
+    A SIM Toolkit (STK) based menu. Primarily for Safaricom MPESA in Kenya, but there are others. When using this option the root code is not used.
 
 3.  ###### USSD or STK push
 
     A session that is not started by dialing a shortcode or launching the STK but is instead started by an API call. Most commonly used to enter a PIN to confirm, but there can be as many steps as needed, just like a regular USSD action.
 
 4.  ###### Variable Longstring
 
-    A USSD session that does not have menus for some choices that need to be made. For example, an airtime top-up using a scratch card might be done by dialing \*123\*voucherCode# where voucherCode is the number from the scratch card.
+    A USSD session that does not have menus for some choices that need to be made. For example, an airtime top-up using a scratch card might be done by dialing \*123\*voucherCode# where voucherCode is the number from the scratch card. This is not recommended for general use since many networks prevent longstrings from working.
 
 
 In **root code** enter the string a user would dial to initiate the session. These usually look like \*123# or \*123\*01#.

customization.md

@@ -7,15 +7,22 @@ permalink: /customization
 
 #### Customize the User Interface
 
-When running a USSD session you can do some simple customizations to the confirm, PIN, processing and completion screens. Simply create a new style in your styles.xml file and define `colorPrimary`, `colorAccent`, and `colorPrimaryDark`. You can try defining other attributes as well, but we have not yet tested or made it easy to tell what will affect what. When making your call to HoverParameters.Builder() simply call the following method:
+When running a USSD session you can do some simple customizations to the confirm, PIN, processing and completion screens. You can add branding to the top of the processing screen using the following method:
+`Hover.setBranding(String brand_name_string, int logo_drawable, context)` This will permanently set the branding until it is called again, so it only needs to be called once, probably wherever Hover.initialize() is called. To change the colors on Hover SDK screens simply create a new style in your styles.xml file and define `colorPrimary`, `colorAccent`, and `colorPrimaryDark`. You can try defining other attributes as well, but we have not yet tested or made it easy to tell what will affect what. When making your call to HoverParameters.Builder() simply call the following method:
 
     new HoverParameters.Builder(this).request("action_id").style(R.style.YOUR_STYLE);
 
+#### Customize the Text
 
-Normally the final USSD message is shown at the end so that the user can see the result of the session. This message can contain errors from the operator or tell the user that their request is being processed. However, in some cases this message is not helpful and you may want to prevent it from being displayed and display your own screen instead. To do this just add the following method to your HoverParameters.Builder call:
+Normally "Transaction in progress" and "processing" are shown on the screen while the USSD session is run. Change "Transaction in progress" by calling `setHeader(string)` and change "processing" by calling `initialProcessingMessage(string)` when you call HoverParameters.Builder:
 
-    new HoverParameters.Builder(this).request("action_id").hideFinalUssd(true);
-    
+    new HoverParameters.Builder(this).setHeader("Working").initialProcessingMessage("please wait");
+
+You can also change the "processing" message for each step. In your action add a description to each step in your action configuration, then on HoverParameters.Builder call `showUserStepDescriptions(true)`. By default, the final USSD message is shown at the end of a session so that the user can see the result. This message can contain errors from the operator or tell the user that their request is being processed. However, in some cases this message is not helpful and you may want to prevent it from being displayed or display your own message instead. To prevent any message from displaying:
+
+    new HoverParameters.Builder(this).request("action_id").finalMsgDisplayTime(0);
+
+The argument is the number of ms, so the same method can also be used to display the message for a shorter or longer period of time. The default is 5000 ms (5 seconds). If you want to display your own message this is done by creating a [parser](/parsing) for the final USSD message and setting the "User Message" field.
 
 #### Customize Accessibility
 
@@ -25,4 +32,4 @@ If you wish to change the text that appears when a user goes to the Accessibilit
 
 You can translate the strings that are part of Hover's UI components. The list of string resources to translate are in the root folder of the Hover SDK's aar packaging called `public.txt` you can find the current english value of those strings in `/res/values/values.xml`
 
-[Next: Hover Tester](/hover-tester)
+[Next: Hover Tester](/hover-tester)

ussd.md

@@ -17,6 +17,12 @@ By using `startActivityForResult()` you will get the content of the session once
 
 If the `resultCode` is `RESULT_OK` then the USSD session was successfully initiated. You can find out the details of the session and whether it successfully completed by inspecting the intent extras provided and parsing the text (see [below](#result)). If the result code is `RESULT_CANCELED` then something went wrong before starting the session. In this case the data intent returned will have a String Extra called `error` which will contain the error message.
 
+In some cases a transaction confirmation based on a [parser](/parsing) can come before `onActivityResult` is called. If you need to know about the pending transaction first then you can listen for the local broadcast intent fired when the pending transaction is first created. This should come before any confirmation and has all the same details about the transaction as onActivityResult.
+
+{% include pending_transaction_listener.html %}
+
+Don't forget to unregister your reciever when your activity is destroyed.
+
 #### Getting a Session Result
 
 The data intent returned in `onActivityResult()` contains the following information if the result is `RESULT_OK`
@@ -45,4 +51,8 @@ If you do not have access to the SIM card or network you wish your users to use
 
 If your USSD session does not seem to be running correctly and you want more visibility into what is happening you can activate the SDK debug environment by calling `.setEnvironment(HoverParameters.DEBUG_ENV)` on your `HoverParameters.Builder()`. This will prevent the Screen Blocker from displaying, allowing you to see the USSD session as it happens, and adding more logging information to the logcat. Do not interact with the session when you see it in this mode; if nothing happens you should recheck your action configuration. If it still doesn't work it is most likely a device specific issue, try with a different device and contact us so we can check the device and help you out. Please do not run debug mode in production: when users see the USSD messages flash across the screen it scares them, the blocking processing screen should always be in place.
 
-[Next: Parse responses](/parsing)
+#### Advanced Usage
+
+In some cases you may need information from the USSD session before you can complete a transaction. For example you may want to get a recipients name so that the user can confirm that it is the correct recipient. To do this you currently need to create 2 separate actions. The first you will configure to run through the USSD steps until the menu that has the information you need. Make that the final step, then create a parser which pulls the details you need out of the message. Use the TRANSACTION_UPDATE broadcast to recieve this information and trigger showing it to the user. Once they have confirmed or otherwise acted based on the information you can then start a second action which you have configured to run the transaction through to completion. Please remember that in some cases your users are charged per USSD session and will not appreciate being charged twice.
+
+[Next: Parse responses](/parsing)