VOIP USSD ANDROID
Loved the tool? Please consider donating πΈ to help it improve!
Usage
|
Extra Features
|
Cordova Plugin
|
Contributors
### by Romell Dominguez
[![](https://raw.githubusercontent.com/romellfudi/assets/master/favicon.ico)](https://www.romellfudi.com/)
## Target Development [High Quality](https://raw.githubusercontent.com/romellfudi/VoIpUSSD/Rev04/snapshot/device_recored.gif):
Interactive with ussd windows, remember the USSD interfaces depends on the System Operative and the manufacturer of Android devices.
## Community Chat
[![Gitter](https://img.shields.io/badge/gitter-join%20us-%23753a89.svg?&style=for-the-badge&logo=gitter&labelColor=ee1a67)](https://gitter.im/romellfudi/VoIpUSSD?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
## Downloads Dashboard
[![Data Studio](https://img.shields.io/badge/DATA%20STUDIO-DOWNLOADS%20REPORT-%23000000.svg?&style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBpZD0iTGF5ZXJfMSIgZGF0YS1uYW1lPSJMYXllciAxIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDcuNDcgMTAwIj48ZGVmcz48c3R5bGU%2BLmNscy0xe2ZpbGw6IzY2OWRmMzt9LmNscy0ye2ZpbGw6IzFhNzNlODt9PC9zdHlsZT48L2RlZnM%2BPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNOTQuMDcsNzIuNzVINTVjLTkuNDYsMC0xNC43Myw2LjU5LTE0LjczLDEzLjYyQzQwLjIyLDkyLjc1LDQ0LjYyLDEwMCw1NSwxMDBoMzguOVY3Mi43NVoiLz48ZWxsaXBzZSBjbGFzcz0iY2xzLTIiIGN4PSI5NC4wNyIgY3k9Ijg2LjE1IiByeD0iMTMuNDEiIHJ5PSIxMy42MyIvPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTUzLjYzLDM2LjI2SDE0LjczQzUuMjcsMzYuMjYsMCw0Mi44NiwwLDQ5Ljg5YzAsNi4zNyw0LjQsMTMuNjMsMTQuNzMsMTMuNjNoMzguOVoiLz48ZWxsaXBzZSBjbGFzcz0iY2xzLTIiIGN4PSI1My42MyIgY3k9IjQ5Ljg5IiByeD0iMTMuNDEiIHJ5PSIxMy42MyIvPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTk0LjA3LDBINTVDNDUuNDksMCw0MC4yMiw2LjU5LDQwLjIyLDEzLjYzYzAsNi4zNyw0LjQsMTMuNjIsMTQuNzMsMTMuNjJoMzguOVYwWiIvPjxlbGxpcHNlIGNsYXNzPSJjbHMtMiIgY3g9Ijk0LjA3IiBjeT0iMTMuNjMiIHJ4PSIxMy40MSIgcnk9IjEzLjYzIi8%2BPC9zdmc%2B)](https://datastudio.google.com/reporting/3328e603-449b-4635-81a5-38e0abebafa4)
## 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](https://github.com/romellfudi/VoIpUSSD/blob/master/ussd-library/src/main/res/xml/ussd_service.xml) `to res/xml` folder (if necessary), this config file allow to link between Application and System Oerative:
```xml
```
### Application Permissions
To use the application, add the following permissions to your AndroidManifest.xml:
```xml
```
### Service Configuration
Include the service in your AndroidManifest.xml for Java:
```xml
```
Or for Kotlin:
```xml
```
**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](https://github.com/romellfudi/VoIpUSSD/issues/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:
```java
Map
> 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:
```kotlin
val map = HashMap>()
map["KEY_LOGIN"] = hashSetOf("espere", "waiting", "loading", "esperando")
map["KEY_ERROR"] = hashSetOf("problema", "problem", "error", "null")
```
2. Instantiate a USSDController object and invoke a USSD code:
For Java:
```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:
```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
}
})
```
3. For custom message handling, structure your code as follows:
For Java:
```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:
```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") {
...
}
}
...
})
```
4. For dual SIM support, specify the SIM slot:
For Java:
```java
ussdApi.callUSSDInvoke(phoneNumber, simSlot, map, new USSDController.CallbackInvoke() {
...
});
```
For Kotlin:
```kotlin
ussdApi.callUSSDOverlayInvoke(phoneNumber, simSlot, map, object : USSDController.CallbackInvoke {
...
});
```
### Static Methods
For Android M and above, check permissions before invoking USSD:
```java
// 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:
```xml
```
#### SplashLoadingService
Add the service to your AndroidManifest.xml:
```xml
```
Start and stop the service around the USSD invocation:
For Java:
```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:
```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)
```
### EXTRA: Use Voip line
In this section leave the lines to call to Telcom (ussd number) for connected it:
```java
ussdPhoneNumber = ussdPhoneNumber.replace("#", uri);
Uri uriPhone = Uri.parse("tel:" + ussdPhoneNumber);
context.startActivity(new Intent(Intent.ACTION_CALL, uriPhone));
```
```kotlin
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
* **cordova-plugin-VoIpUSSD** - [Ramy Mokako](https://github.com/rmxakalogistik/cordova-plugin-VoIpUSSD#cordova-plugin-voipussd)
## Contributors β¨
[![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors-)
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
## License
[![GNU GPLv3 Image](https://www.gnu.org/graphics/gplv3-127x51.png)](http://www.gnu.org/licenses/gpl-3.0.en.html)
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](https://www.gnu.org/licenses/gpl.html) as
published by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.