How to set up Fortumo's Android SDK

The Android SDK relies on services (android application components, not related to the service you created in your dashboard), which handle all communication between your application and the Fortumo servers. To use Android SDK, your application must request the proper permissions and integrate services and an activity into its Manifest.

Download the Android SDK

Download the Android SDK from your Fortumo Dashboard. You can find it under your service's Setup tab and add it to your app's lib folder. Don't forget to add the jar file as library in your IDE's project properties. In Android Studio you could add the following line to the dependencies in the project's build.gradle file: compile files('libs/fortumo-in-app-android-sdk.jar');

Declaring Android SDK objects

1
2
3
4
5
6
7
8
9
10
11
<!-- Declare these objects, this is part of Fortumo's Android SDK, and should not be called directly -->
<receiver android:name="mp.MpSMSReceiver">
<intent-filter>
  <action android:name="android.provider.Telephony.SMS_RECEIVED" />
</intent-filter>
</receiver>
<service android:name="mp.MpService" />
<service android:name="mp.StatusUpdateService" />
<activity android:name="mp.MpActivity"
            android:theme="@android:style/Theme.Translucent.NoTitleBar"
            android:configChanges="orientation|keyboardHidden|screenSize" />

Permissions

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.SEND_SMS" />

<!-- Define your own permission to protect payment broadcast -->
<permission android:name="com.your.domain.PAYMENT_BROADCAST_PERMISSION"
              android:label="Read payment status"
              android:protectionLevel="signature" />
<!-- "signature" permission granted automatically by system, without notifying user. -->
<uses-permission android:name="com.your.domain.PAYMENT_BROADCAST_PERMISSION" />
  • For security purposes, your own broadcast should be protected by a permission;
  • For example, you can define and add permissions into your AndroidManifest.xml file as shown above.

Please be aware that RECEIVE_SMS, READ_SMS and SEND_SMS permissions might require you to fill out the Permissions Declaration Form to qualify Google Play policy exceptions. You can find more details about the policy and its exceptions in Google Play Developer Policy Center and in the Help Center.

Also note that since Android M, so called dangerous permissions have to be requested during runtime. INTERNET and ACCESS_NETWORK_STATE will still be granted during install, but READ_PHONE_STATE and RECEIVE_SMS/SEND_SMS have to be requested during runtime. We require READ_PHONE_STATE in order to determine mobile country code and mobile network code from the sim card, so that we can figure out if this enduser can be charged through Fortumo. Therefore, before you use

1
MpUtils.isSupportedOperator(Context context, String serviceId, String appId);

you have to request READ_PHONE_STATE from the enduser, otherwise this request will always return false. After determining that the user can be charged through Fortumo, before you can actually launch Fortumo's PaymentActivity, you have to request the SEND_SMS permission.

1
2
3
4
// when extending PaymentActivity to launch the payment flow
makePayment(pr);
// when starting the activity yourself
startActivityForResult(payment.toIntent(getActivity()), 42);

After the user grants SEND_SMS permission, the payment flow will work normally. The code snippets shown here are explained in more detailed in the next section and were just presented to indicate what methods require that the user grants permission. More information on that topic can be found here.

Implementing a BroadcastReceiver

Implement your own BroadcastReceiver to track payment status, should be protected by signature permission.

1
2
3
4
5
6
7
8
<!-- Implement you own BroadcastReceiver
to track payment status, should be protected by "signature" permission -->
<receiver android:name=".PaymentStatusReceiver"
           android:permission="com.your.domain.PAYMENT_BROADCAST_PERMISSION">
  <intent-filter>
  <action android:name="mp.info.PAYMENT_STATUS_CHANGED" />
</intent-filter>
</receiver>

Supporting tablets

If your app does not need to make phone calls, we can add this, so the app could be installed on tablets.

1
2
3
<!-- If your app doesn't need to make phone calls, you can add this, so the app
could be installed on tablets. -->
<uses-feature android:name="android.hardware.telephony" android:required="false" />

Full example of AndroidManifest.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<!-- Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.SEND_SMS" />

<!-- Define your own permission to protect payment broadcast -->
<permission android:name="com.your.domain.PAYMENT_BROADCAST_PERMISSION"
             android:label="Read payment status"
             android:protectionLevel="signature" />
<!-- "signature" permission granted automatically by system, without notifying user. -->
<uses-permission android:name="com.your.domain.PAYMENT_BROADCAST_PERMISSION" />

<application android:icon="@drawable/ic_launcher" android:label="@string/app_name">
  <!-- Declare these objects, this is part of Fortumo's Android SDK,
  and should not be called directly -->
  <receiver android:name="mp.MpSMSReceiver">
    <intent-filter>
    <action android:name="android.provider.Telephony.SMS_RECEIVED" />
  </intent-filter>
</receiver>
<service android:name="mp.MpService" />
<service android:name="mp.StatusUpdateService" />
<activity android:name="mp.MpActivity"
           android:theme="@android:style/Theme.Translucent.NoTitleBar"
           android:configChanges="orientation|keyboardHidden|screenSize" />

  <!-- Implement you own BroadcastReceiver to track payment status,
  should be protected by "signature" permission -->
<receiver android:name=".PaymentStatusReceiver"
          android:permission="com.your.domain.PAYMENT_BROADCAST_PERMISSION">
  <intent-filter>
    <action android:name="mp.info.PAYMENT_STATUS_CHANGED" />
  </intent-filter>
</receiver>

<!-- Other application objects -->
<activity android:label="@string/app_name" android:name=".YourActivity">
  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>
...

Configuring ProGuard

The embed resources used by the payment library are in “mp.res” namespace, but the namespace isn’t referenced directly so ProGuard assumes that these classes are never used. In order to fix that, the following lines must be added to the configuration file:

1
-keep class mp.** { *; }

The auto-generated ProGuard configuration file, where these changes need to be done, is named proguard-project.txt by Eclipse. In Android Studio the file is called proguard-rules.pro and you'll find it in your project's app/ folder.

Help us improve our Merchants Portal. Was this article helpful?