Added all the documentation pages

Author: ishuah

_config.yml

@@ -43,3 +43,6 @@ title: Hover Documentation
 #   - vendor/cache/
 #   - vendor/gems/
 #   - vendor/ruby/
+
+include:
+  - actions.md

actions.md

@@ -0,0 +1,61 @@
+---
+layout: page
+---
+
+# Actions
+
+Hover’s SDK uses _actions_ you create to navigate menus on user devices. Typically each action represents a path through USSD menus. Once you create an action you can call it from your application code by passing its `action_id` to the Hover SDK.
+
+Actions can be updated anytime from within your Hover dashboard so that you do not have to update your whole app when a USSD service changes. To create actions sign in to your Hover account then go to <% if current\_user.present? && !current\_user.view? %><%= link\_to "create an action", new\_organization\_custom\_action\_path(current\_user.organization), target: :\_blank %><% else %><%= link\_to "create an action", organizations\_path, target: :\_blank %><% end %>.
+
+###### Actions consist of
+
+-   **Name** of your choice, for example "Send Money".
+-   **Mobile networks**/SIM cards that can run the USSD service.
+-   **Root code**, the shortcode used to dial the USSD service.
+-   The USSD menu **steps**. See below.
+
+See our <%= link\_to "blog post", "https://medium.com/use-hover/45aa9dd9dfa", target: :\_blank %> for more on converting USSD menus into actions.
+
+#### Creating an Action
+
+Log into your Hover account and choose “New Action” from the dashboard. Give the action a memorable name. We recommend using the operator name and the type of action for easy reference (eg Tigo Send Money). Then choose the country and mobile operator your action will work with. If you’d like to support the same USSD function across multiple networks, you will need to create a unique action for each operator (eg Tigo Check Balance, MTN Check Balance) if the USSD root code and steps are different.
+
+In **root code** enter the string a user would dial to initiate the session. These usually look like \*123# or \*123\*01#.
+
+Finally enter the **steps** for your action. Each step corresponds to a selection from a USSD menu. There are three types of steps:
+
+1.  ###### Number
+    
+    Constant choices such as entering “1” to reach My Account.
+    
+    Corresponds to the user entering a number from a list of options and pressing “Send”. The ‘Input’ is the number Hover’s SDK will enter on behalf of the user. If there is a confirmation dialog without a number choice, create a number step with the value of a single dash `-`. This is ONLY required for dialogs in-between other steps, not at the end of the session.
+    
+2.  ###### Variable
+    
+    Entries that change at runtime, such as amount to be sent.
+    
+    Variable indicates that Hover’s SDK will enter a value that must be provided by your app to the SDK at runtime. It might be a value that your app passes to the SDK after getting input by the user, or something else that your app chooses at runtime. The “Input” is an alphanumeric identifier which you provide to the SDK when initiating a transaction; see <%= link\_to %Q\[Run a USSD session\], page\_path("docs/ussd") %>. Variable steps are useful for actions like send money or pay bill, for example, where users need to enter business numbers and amounts
+    
+3.  ###### PIN prompt
+    
+    Displays a PIN entry for the user.
+    
+    PIN steps enter the user's PIN during the session. When running an action that contains a PIN step, Hover's SDK will display a secure prompt to the user before starting the session. The PIN is encrypted and temporarily stored using the Android Keystore, entered into the session at the appropriate time and then deleted. Note: The PIN **never** leaves the device.
+    
+
+<%= render "pages/docs/image\_with\_caption", image: "docs/sdk-pin.png", title: "PIN Entry", text: "For actions that include a 'pin' step, Hover's SDK displays this pin entry screen at the start of the session. The PIN is encrypted and temporarily stored, then inserted into the USSD session at the appropriate time and then deleted. The pin never leaves the user's device. The background color and text color are #{link\_to %Q\[customizable\], page\_path("docs/customization")}." %>
+
+Sometimes simple actions like balance checks and account information requests have only a root code and no steps. In this case enter the root code and leave the steps blank.
+
+Later you can add _parsers_ to your action to make information such as confirmation details and USSD session status accessible to your application code.
+
+#### Using Actions
+
+Since a USSD action will only run on a specific SIM card, Hover's SDK provides a number of methods to help you find out which actions you can run on a user's device, even for dual SIM devices.
+
+You must get the `READ_PHONE_STATE` permission and call `Hover.initialize()` before using any of Hover's helper methods. You should check if the permission has been granted before calling the method: if permission is not granted the method will throw an exception.
+
+If you want to know if you can run a particular action on the user's SIM(s) you can call `Hover.isActionSimPresent(actionId, context);`. If you want to get a list of all your actions that will run on any of a user's present SIM cards you can call `Hover.getAllValidActions(context);` which will return a list of actions. There are also helpers for getting all the SIM cards present and for presenting a SIM choice interface to the user.
+
+[Next: Install](/docs/installation)

customization.md

@@ -0,0 +1,27 @@
+---
+layout: page
+---
+
+# 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:
+
+    new HoverParameters.Builder(this).request("action_id").style(R.style.YOUR_STYLE);
+    
+
+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:
+
+    new HoverParameters.Builder(this).request("action_id").hideFinalUssd(true);
+    
+
+#### Customize Accessibility
+
+If you wish to change the text that appears when a user goes to the Accessibility Settings screen you can do so by defining the strings `access_service_summary` and `access_service_descript` in your `strings.xml` file. `access_service_descript` is the one that users will see on the settings page.
+
+#### Translate
+
+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](/docs/hover-tester)

dual-sim.md

@@ -0,0 +1,42 @@
+---
+layout: page
+---
+
+# Dual SIM
+
+The Hover SDK automatically supports dual SIM devices without any extra configuration. However, sometimes you may need to read the user's SIM cards, get them to choose a SIM, or something else. Hover provides a number of helper methods as well as it's own data model for SIM information. Android's APIs for dual SIM devices are poorly documented and were only introduced in version 5.1. Hover's helpers work on all supported Android versions 4.3 and up.
+
+When you create a Hover action you specify a country and network. This is used to match the SIM cards that work with that the USSD service your action represents. When your app runs the action using the [HoverParameter.Builder() intent](/docs/ussd), the correct SIM card is chosen automatically using the configuration you created. If the correct SIM card is present it will be used to dial the USSD root code regardless of which slot the SIM card is in or the user's system settings regarding which SIM to dial with. If the correct SIM card is not present an error will be returned to your app in onActivityResult() with RESULT\_CANCELED. If for some reason the user has two SIM cards that work with your action inserted, they will be shown a simple dialog asking them to choose one before proceeding
+
+#### Reading a user's SIM cards
+
+You must get the READ\_PHONE\_STATE permission THEN call `Hover.initialize()` BEFORE using any SIM card methods below, otherwise the SIM information will be empty. You can do this yourself or using Hover's [permission helper](/docs/permissions).
+
+The simplest SIM card helper just lets you check if the correct SIM for your action is present: `Hover.isActionSimPresent(actionID, context)`.
+
+You might instead want to get a list of all the user's currently inserted SIM cards. To do so you can call `Hover.getPresentSims(context)` which returns a list of Hover's [SimInfo](#sim-info-object) objects.
+
+#### Choosing an action using present SIMs
+
+A common use case is to choose an action to run based on the user's present SIM card(s). This can be done by calling `ActionHelper.requestActionChoice(actionIds, actionChoiceListener, context)`. You must specify an ActionChoiceListener which is the following interface:
+
+    public interface ActionChoiceListener {
+    	void onActionChosen(String actionId);
+    	void onCanceled();
+    }
+
+This is because if the user has a dual SIM device and more than one SIM matches your actions, then the callback will be called once they have selected the SIM from a simple dialog. Note that this dialog will actually present the user with a list of _SIM choices_ not action names. If only one SIM matches, the callback will be called immediately. If no SIMs match an exception will be thrown. If the user cancels the dialog `onCanceled` will be called. The following is an example:
+
+<%= render "pages/snippets/action\_choice\_example" %>
+
+_The contexts in this example should be activities, since a dialog may need to be shown to the user._
+
+#### The SimInfo Object
+
+SimInfo is a Plain Old Java Object (POJO) included in the Hover SDK to simplify reading of SIM info in Android.
+
+You do not instantiate SimInfo objects yourself, you must get them from a method (such as those above) that returns them!
+
+This object can give you detailed information about each SIM card and reads consistently across all supported versions of Android (4.3+). See the [javadoc](#) for how to get the detailed information.
+
+[Next: Webhooks](/docs/webhooks)

hover-tester.md

@@ -0,0 +1,19 @@
+---
+layout: page
+---
+
+# Hover Tester
+
+Hover tester is a lightweight app that allows you to test actions on a real Android device and SIM card. It can be built <%= link\_to "from source", "https://github.com/UseHover/Tester", target: :\_blank %>, or you can visit your Hover dashboard to download a precompiled APK. The precompiled APK includes an API key linked to your account so you can test actions without writing code.
+
+Hover Tester is in beta release. Please contact us via the chat button below or at <%= mail\_to "support@usehover.com", "support@usehover.com", { target: '\_blank' } %> if you have questions about the app.
+
+#### Usage instructions
+
+To use Hover Tester you need a <%= link\_to "Hover account", new\_user\_registration\_path, target: :\_blank %>, an Android device with a SIM card on a mobile network of your choice, and at least <%= link\_to "one action configured", page\_path("docs/actions") %> to run on that network.
+
+1.  Compile the Hover Tester APK from source, or download the pre-built version, and install it on your Android device.
+2.  Open Hover Tester and tap “GRANT PERMISSIONS”. Allow all permissions requested.
+3.  Tap “ADD INTEGRATION”, then tap the name of the action you want to test.
+4.  The action’s name and ID should be displayed on the main screen. Tap it, and then use the play button to run the action. The result is displayed once the USSD session completes.
+5.  If you update your action or add new actions, use the refresh button in the bottom right of the main screen to sync the changes with Hover Tester.

installation.md

@@ -0,0 +1,51 @@
+---
+layout: page
+---
+
+# Installation
+
+If you are new to Android or starting your app from scratch, we have an <%= link\_to %Q\[app on Github\], "https://github.com/UseHover/HoverStarter", target: :\_blank %> that can help you get going faster. Just follow the instructions in the README.
+
+#### Create an App
+
+A Hover “app” represents your Android application on Hover’s server. Each app has a unique API token, and a page where you can view information about users’ USSD sessions.
+
+From your account dashboard click “New app”. The app name is for your reference only, it won't be visible to users. Enter the exact package name of your app, and an optional https webhook URL where Hover will post a JSON representation of USSD session details. The package name must match the applicationId in your app/build.gradle
+
+Save your new app and note the API token for use in the next step.
+
+###### Webhook
+
+You can add a webhook for each app to notify you any time a transaction is created or updated. You can even use this to keep your server database up to date without having to write a bunch of Android code. Simply enter a url that can recieve POST requests with a JSON payload. See [webhooks](/docs/webhooks) for more.
+
+#### Install the SDK
+
+<%= render "pages/docs/current\_version" %>
+
+To include the SDK in your app, add Hover to your app-level build.gradle dependencies:
+
+<%= render "pages/snippets/gradle\_dependencies" %>
+
+###### Build Notes:
+
+This SDK supports Android 4.3 - 8.0 (API 18-26). It can be used in apps with a wider range, but you must add the following to your Manifest: `<uses-sdk tools:overrideLibrary="com.hover.sdk"/>` and check the API level yourself and only make a call to the Hover SDK if the user’s Build API is within that range: `if (Build.VERSION.SDK_INT >= 18)`
+
+  
+
+There can be various build errors and conflicts depending on which Android Studio and Gradle Build Tools version you are using and which Android SDK you target. We recommend Android Studio 2.3+. The Hover SDK also depends on some of the Android Support libraries. If there is a conflict when you build, you can try to not use the transitive dependencies (`transitive = false` or the `exclude` keyword in your build file) and include the support libraries version you wish to use. We cannot guarantee that doing this will not cause issues. In case you encounter an issue, please feel free to [get in touch](javascript:void(0)) for help. You can list our dependencies by running `./gradlew app:dependencies`.
+
+Then include your API token as application level meta-data in your AndroidManifest.xml:
+
+<%= render "pages/snippets/api\_token" %>
+
+To find or create an API token visit your <%= link\_to "Hover dashboard", organizations\_path, target: :\_blank %> and click on your app, or make a new app. **The package name in our dashboard must match that of your actual app for the token to work.**
+
+#### Initialize
+
+First have your app initialize the Hover SDK by calling `Hover.initialize()`. This should ideally happen at app launch.
+
+<%= render "pages/snippets/initialize" %>
+
+This call downloads your configuration information from the Hover server. If the `READ_PHONE_STATE` permission has been granted it also reads the SIM cards the user has present and listens for changes to them.
+
+[Next: Run a USSD session](/docs/ussd)