README

Aguva Ussd软件包简介

Aguva Ussd是一个现代且灵活的USSD应用解决方案，支持多种语言，如英语和斯瓦希里语，并可按需集成其他语言。其语法清晰且复杂，确保了出色的用户体验。此外，它还包含一个内置的USSD模拟器，简化了应用程序的调试和维护。

安装

运行以下命令

composer require aguva/ussd:dev-main

发布软件包支持文件

php artisan vendor:publish --provider="Aguva\Ussd\Providers\UssdServiceProvider" --tag=aguva-ussd-lang --force

运行迁移

php artisan migrate

在根项目的 .env 文件中添加以下变量

DEFAULT_MESSAGE= # The default message to show when no other message is available
RESTRICT_TO_WHITELIST=true # Set to false to allow all msisdns
LOG_USSD_REQUEST=true # Set to true to log all ussd request payloads from provider
WHITELIST_MSISDNS="254705799644" # Comma separated list of msisdns to whitelist
END_SESSION_SLEEP_SECONDS=2 # Delay in seconds before ending session
USSD_CODE=657 # This is the ussd code given to you by your provider eg 999
ONLINE_ENDPOINT='api/process-payload/55034fd5-bd23h5d9948f' # The endpoint to receive ussd payloads from provider

在根项目的 app/Repositories 目录下创建一个 UssdProcessor.php 文件，并添加以下模板代码。这是您的试验场，尽情发挥吧

注意：将每个 a 方法视为一个新的USSD屏幕实例

    <?php
    namespace App\Repositories;
    use Aguva\Ussd\Repositories\Handler;

    class UssdProcessor
    {
        // Distinguish if it's a new user (first dial) or a registered user
        static function activityHome(Handler $handler, $params)
        {
            if (array_key_exists('newUser', $handler->userInput) && $handler->userInput['newUser']) {
                return self::activityHomeNewUser($handler, $params);
            }
            return self::activityHomeExistingUser($handler, $params);
        }
    
        // This is an existing user
        static function activityHomeExistingUser(Handler $handler, $params)
        {
            $handler->message = __('ussd.welcome_new_user', ['name' => $handler->user->first_name]);
            $menu = [
                1 => [
                    'text' => __('ussd.item_home'),
                    'activity' => 'activityHome',
                ],
                2 => [
                    'text' => __('ussd.item_choose_language'),
                    'activity' => 'activityChooseLanguage',
                ],
                3 => [
                    'text' => __('ussd.item_quit'),
                    'activity' => 'activityQuit',
                ]
            ];
            $handler->menuItems = $menu;
            return self::activityReturnValidMessage($handler);
        }
    
        // This is a new user
        static function activityHomeNewUser(Handler $handler, $params)
        {
            $handler->message = __('ussd.welcome_registered_user', ['name' => '']);
            $menu = [
                1 => [
                    'text' => __('ussd.item_choose_language'),
                    'activity' => 'activityChooseLanguage',
                ],
                2 => [
                    'text' => __('ussd.item_quit'),
                    'activity' => 'activityQuit',
                ]
            ];
    
            $handler->menuItems = $menu;
            return self::activityReturnValidMessage($handler);
        }
    
        // Exit the application
        static function activityQuit(Handler $handler, $params)
        {
            $handler->message = __('ussd.item_message_quit');
            $handler->end = true;
            return self::activityReturnValidMessage($handler);
        }
    
        // Choose app language
        public static function activityChooseLanguage(Handler $handler, $params)
        {
            $handler->message = __('ussd.item_choose_language');
            $languageLookUp = ['1' => 'en', '2' => 'sw'];
            $handler->userInput['localeLookup'] = $languageLookUp;
    
            $handler->menuItems = [
                '1' => [
                    'text' => __('ussd.item_language_english'),
                    'activity' => 'activityChangeLanguage'
                ],
                '2' => [
                    'text' => __('ussd.item_language_swahili'),
                    'activity' => 'activityChangeLanguage'
                ],
                '0' => [
                    'text' => __('ussd.item_navigation_home'),
                    'activity' => 'activityHome'
                ]
            ];
    
            return self::activityReturnValidMessage($handler);
        }
    
        // Change the app language
        public static function activityChangeLanguage(Handler $handler, $params)
        {
            if (!collect($handler->userInput['localeLookup'])->has($handler->ussdString)) {
                return self::activityHome($handler, $params);
            }
    
            $locale = $handler->userInput['localeLookup'][$handler->ussdString];
            $handler->user->locale = $locale;
            $handler->user->save();
    
            $handler->setLang();
    
            $handler->message = __('ussd.item_locale_saved');
    
            $handler->menuItems = [
                '0' => [
                    'text' => __('ussd.item_navigation_home'),
                    'activity' => 'activityHome'
                ]
            ];
            return self::activityReturnValidMessage($handler);
        }
    
        // Returned message
        public static function activityReturnValidMessage(Handler $handler)
        {
            if ($handler->invalidInput) {
                $handler->message = __('ussd.enter_valid_input') . " $handler->ussdString\n$handler->message";
            }
            return $handler;
        }
    
        /**
         * ALL YOUR OTHER MENUS WILL BE WRITTEN HERE... FEEL FREE TO PLAY AROUND
         */
    }

模拟器URL

The ussd simulator can be found in the url "/simulator". Kindly note that it mimics a live ussd environment meaning that you have to click "new session" button whenever you want to simulate the start of a new session.

使用的队列工作进程

请确保您监听以下队列，该队列用于将ussd会话数据保存到数据库中

save-ussd-message

您可以选择以下任一选项；

注意：安装horizon控制台或beanstalkd控制台以帮助您监控队列，并安装必要的相应Laravel软件包。

卸载

composer remove aguva/ussd

安全漏洞

如果您在库中发现安全漏洞，请发送电子邮件至Cyril Aguvasu。所有安全漏洞都将得到及时处理。

许可

该库由Cyril Aguvasu所有并维护。

aguva / ussd

维护者

详细信息