Skip to content

Latest commit

 

History

History
executable file
·
350 lines (275 loc) · 14.8 KB

README.md

File metadata and controls

executable file
·
350 lines (275 loc) · 14.8 KB
Raw

VOIP USSD ANDROID

Platform API License Workflow Gitter Bintray Bintray Kotlin Android Arsenal Jitpack

Loved the tool? Please consider donating 💸 to help it improve!

sponsor voip android library

Usage    |    Extra Features    |    Cordova Plugin    |    Contributors

by Romell Dominguez

Target Development High Quality:

Jitpack

Interactive with ussd windows, remember the USSD interfaces depends on the System Operative and the manufacturer of Android devices.

Community Chat

Gitter

Downloads Dashboard

Data Studio

USSD LIBRARY

Implementations

Add the following dependency in your app's build.gradle configuration file:

Repository implementation Status
jcenter() 'com.romellfudi.ussdlibrary:ussd-library:1.1.i' DEPRECATED
jcenter() 'com.romellfudi.ussdlibrary:kotlin-ussd-library:1.1.k' DEPRECATED
maven { url https://jitpack.io } 'com.github.romellfudi.VoIpUSSD:ussd-library:1.4.a' READY
maven { url https://jitpack.io } 'com.github.romellfudi.VoIpUSSD:kotlin-ussd-library:1.4.a' READY
  • Writing a config xml file from here to res/xml folder (if necessary), this config file allow to link between Application and System Oerative:
<?xml version="1.0" encoding="utf-8"?>
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    .../>

Application Permissions

To use the application, add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Service Configuration

Include the service in your AndroidManifest.xml for Java:

<service
    android:name="com.romellfudi.ussdlibrary.USSDService"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>
    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/ussd_service" />
</service>

Or for Kotlin:

<service
    android:name="com.romellfudi.ussdlibrary.USSDServiceKT"
    android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
    <intent-filter>
        <action android:name="android.accessibilityservice.AccessibilityService" />
    </intent-filter>
    <meta-data
        android:name="android.accessibilityservice"
        android:resource="@xml/ussd_service" />
</service>

NOTE: You may want to override android:notificationTimeout="0"to a corresponding value of 200 or avobe by copying the contents of @xml/ussd_service to the xml dir. Otherwise it is possible that the library will miss accessibility events during operation, resulting is unintended behaivours (e.g not reading up to date prompts #115 )

Usage Instructions

  1. Create a HashMap to identify USSD response messages for login and error scenarios:
KEY MESSAGE String Messages
KEY_LOGIN "espere", "waiting", "loading", "esperando", ...
KEY_ERROR "problema", "problem", "error", "null", ...

For Java:

Map<String, HashSet<String>> map = new HashMap<>();
map.put("KEY_LOGIN", new HashSet<>(Arrays.asList("espere", "waiting", "loading", "esperando")));
map.put("KEY_ERROR", new HashSet<>(Arrays.asList("problema", "problem", "error", "null")));

For Kotlin:

val map = HashMap<String, HashSet<String>>()
map["KEY_LOGIN"] = hashSetOf("espere", "waiting", "loading", "esperando")
map["KEY_ERROR"] = hashSetOf("problema", "problem", "error", "null")
  1. Instantiate a USSDController object and invoke a USSD code:

For Java:

USSDApi ussdApi = USSDController.getInstance(context);
ussdApi.callUSSDInvoke(phoneNumber, map, new USSDController.CallbackInvoke() {
    @Override
    public void responseInvoke(String message) {
        // Handle the USSD response
        String dataToSend = "data"; // Data to send to USSD
        ussdApi.send(dataToSend, new USSDController.CallbackMessage() {
            @Override
            public void responseMessage(String message) {
                // Handle the message from USSD
            }
        });
    }

    @Override
    public void over(String message) {
        // Handle the final message from USSD or error
    }
});

For Kotlin:

val ussdApi = USSDController.getInstance(context)
ussdApi.callUSSDOverlayInvoke(phoneNumber, map, object : USSDController.CallbackInvoke {
    override fun responseInvoke(message: String) {
        // Handle the USSD response
        val dataToSend = "data" // Data to send to USSD
        ussdApi.send(dataToSend) { responseMessage ->
            // Handle the message from USSD
        }
    }

    override fun over(message: String) {
        // Handle the final message from USSD or error
    }
})
  1. For custom message handling, structure your code as follows:

For Java:

// Example of selecting options from USSD menu
ussdApi.callUSSDInvoke(phoneNumber, map, new USSDController.CallbackInvoke() {
    ...
    // Select the first option
    ussdApi.send("1", new USSDController.CallbackMessage() {
        ...
        // Select the next option
        ussdApi.send("1", new USSDController.CallbackMessage() {
            ...
        });
    });
    ...
});

For Kotlin:

// Example of selecting options from USSD menu
ussdApi.callUSSDOverlayInvoke(phoneNumber, map, object : USSDController.CallbackInvoke {
    ...
    // Select the first option
    ussdApi.send("1") {
        ...
        // Select the next option
        ussdApi.send("1") {
            ...
        }
    }
    ...
})
  1. For dual SIM support, specify the SIM slot:

For Java:

ussdApi.callUSSDInvoke(phoneNumber, simSlot, map, new USSDController.CallbackInvoke() {
    ...
});

For Kotlin:

ussdApi.callUSSDOverlayInvoke(phoneNumber, simSlot, map, object : USSDController.CallbackInvoke {
    ...
});

Static Methods

For Android M and above, check permissions before invoking USSD:

// Check if accessibility permissions are enabled
ussdApi.verifyAccessibilityAccess(Activity);
// Check if overlay permissions are enabled
ussdApi.verifyOverlay(Activity);

Overlay Service Widget (Optional)

For Android O and above, use the OverlayShowingService to handle overlay permissions. Add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACTION_MANAGE_OVERLAY_PERMISSION" />

SplashLoadingService

Add the service to your AndroidManifest.xml:

<service android:name="com.romellfudi.ussdlibrary.SplashLoadingService"
         android:exported="false" />

Start and stop the service around the USSD invocation:

For Java:

Intent svc = new Intent(activity, SplashLoadingService.class);
// Show the overlay
activity.startService(svc);
// Invoke USSD and handle responses
...
// Dismiss the overlay
activity.stopService(svc);

For Kotlin:

val svc = Intent(activity, SplashLoadingService::class.java)
// Show the overlay
activity.startService(svc)
// Invoke USSD and handle responses
...
// Dismiss the overlay
activity.stopService(svc)

Jitpack

EXTRA: Use Voip line

In this section leave the lines to call to Telcom (ussd number) for connected it:

ussdPhoneNumber = ussdPhoneNumber.replace("#", uri);
Uri uriPhone = Uri.parse("tel:" + ussdPhoneNumber);
context.startActivity(new Intent(Intent.ACTION_CALL, uriPhone));
ussdPhoneNumber = ussdPhoneNumber.replace("#", uri)
val uriPhone = Uri.parse("tel:$ussdPhoneNumber")
context.startActivity(Intent(Intent.ACTION_CALL, uri))

Once initialized the call will begin to receive and send the famous USSD windows

Cordova Plugin

Contributors ✨

All Contributors

Thanks goes to these wonderful people (emoji key):


Romell D.Z. 福迪
💻
Abdullahi Yusuf
💻
Mohamed Hamdy Hasan
💻
Mohamed Daahir
💻
Ramy Mokako
🔌
Md Mafizur Rahman
💻

License

GNU GPLv3 Image

VoIpUSSD is a Free Library Software: You can use, study share and improve it at your will. Specifically you can redistribute and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.