README

使用客户端

客户端用于发送push通知、短信和设置电话呼出任务，以及获取发送和呼出结果。

标准安装

composer require druidvav/badapush-client

对于每个动作，您需要在badapush.ru网站上创建一个服务并获取API密钥。

使用两个主要类进行工作

Druidvav\BadapushClient\BadapushQueueClient — 用于通过队列发送消息（仅限push和sms）
Druidvav\BadapushClient\BadapushClient — 用于直接发送消息

初始化客户端

对于symfony来说，是这样的

queue_client:
  class: Druidvav\BadapushClient\BadapushQueueClient
  arguments: [ "API_KEY" ]
client:
  class: Druidvav\BadapushClient\BadapushClient
  arguments: [ "API_KEY" ]

或者直接

$queueClient = new Druidvav\BadapushClient\BadapushQueueClient("API_KEY");
$client = new Druidvav\BadapushClient\BadapushClient("API_KEY");

发送短信

我们建议通过队列发送短信。

use Druidvav\BadapushClient\Payload\Payload; 
// Symfony
$this->get('queue_client')->sendPayload(Payload::create($phoneNumber, $message));
// PHP
$queueClient->sendPayload(Payload::create($phoneNumber, $message));

Push通知（APNS、FCM）

发送通知

我们建议通过队列发送push通知。

$payload = new Payload($identifier); // Идентификатор устройства
$payload->setIsDevelopment($bool); // Только для APNS, true или false, можно не использовать вообще
$payload->setPayload([ 'key' => 'value', 'key' => 'value' ]); // Информация которая будет передана в приложение
$payload->setPayloadAps([
    'message' => 'asd123',
    'sound' => 'default',
    'content-available' => 1,
    'priority' => 5,
    'badge' => 3,
]); // Только для APNS, информация из объекта aps.
$this->get('queue_client')->sendPayload($payload);

收集错误信息

如果您通过队列发送了通知，则可以通过特殊方法获取投递错误。实际上，只需处理带有错误设备标识符的错误即可。

$fromId = 0;
do {
    $list = $this->get('queue_client')->retrieveMessages($fromId);
    foreach ($list as $row) {
        $fromId = $row->getId();
        if ($row->isInvalidId()) {
            // Обрабатываем ошибку идентификатора устройства.
            // Сам идентификатор можно получить так:
            // $row->getDeviceId()
        }
    }
} while (sizeof($list) > 0);

“Badapush Caller”电话呼出任务

发送电话呼出任务

电话呼出任务的发送仅在没有队列的情况下工作。

use Druidvav\BadapushClient\Payload\CallerPayload;

$payload = CallerPayload::create($phoneNumber); // Указываем номер телефона, по которому звонить
$payload->setExternalId($externalId); // ID в вашей системе, чтобы вы могли опознать результат обзвона. Например, номер посылки.
$payload->setTimezone($timezone); // Необязательно, часовой пояс клиента в том виде, в каком его отдает dadata.
$payload->setGroup($groupName); // Строка с названием очереди обзвона для разбиения задач на группы. Если разбивка не нужна — укажите одну строку для всех задач.
$payload->setResultOptions([
    'ok' => 'Готово',
    'received' => 'Уже забрал посылку'
]); // Не обязательно, варианты ответа доступные для выбора обзвонщику. Если не указать — будет только ok. Нужно указывать только если вы потом будете обрабатывать результаты обзвона.
$payload->setDataFields([
    'key' => $value,
    'key' => $value
]); // Не обязательно, значения дополнительных полей передаваемых задаче обзвона, подробнее смотри в разделе "Настройка сервисов". Если не указывать доступно только решение "ok" => "Готово!"
$this->get('client')->sendPayload($payload);

取消电话呼出任务

例如，您为提醒客户取包裹设置了任务，而他们已经取了包裹。或者，您已经收集了所需的信息。为了防止呼叫者无谓地打电话，最好取消任务。任务通过 externalID 取消，如果没有与提供的 externalId 相关的任务，则没有问题。不需要检查任务是否真的已创建。

$this->get('client')->cancelCallsByExternalId($externalId, 'Причина отмены');

收集任务执行结果

以下是一个收集已完成电话呼出任务信息的代码示例。

$fromId = 0;
do {
    $results = $this->get('client')->retrieveMessages($fromId); // Получаем пачку сообщений для обработки. $maxId, если не равен нулю помечает все сообщения с id до fromId включительно как прочитанные и больше не возвращает их в следующих запросах. По аналогии с API Telegram.
    foreach ($results as $result) {
        $fromId = $result->getId();
        if (!$result->getExternalId()) { // Если мы забыли передать externalId, то обработать не сможем :)
            continue;
        }
        $response = $result->getResponse();
        switch ($response['result']) {
            case 'invalid_job':
                // Обзвонщик нажал кнопку, что задачу невозможно выполнить
                break;
            case 'invalid_device_id':
                // Обзвонщик нажал кнопку, что мобильный телефон неправильный
                break;
            case 'cancel':
                // Задача была отменена по API
                break;
            case 'delay':
                // Звонок отложен обзвонщиком (недозвон, либо просьба перезвонить)
                break;
            case 'ok':
            case 'received': // Или любой из вариантов переданных в setDataFields 
                // Обзвонщик выполнил задачу, выбрав один из вариантов
                break;
            default: throw new Exception('Unknown code: ' . $response['result']);
        }
    }
} while (sizeof($results) > 0); // Выполняем пока не обработаем все результаты

在badapush中设置服务

“Badapush Caller”服务

电话呼出服务在创建后即可使用。如果要在电话呼出界面中添加额外的字段或添加链接到您的管理界面，则需要设置“配置字段”字段。该字段应包含正确格式的JSON。

示例

[
  { "field": "name", "title": "Клиент" },
  { "field": "package_id", "title": "Посылка", "url_field": "package_url" }
]

在此处指定了具有特定字段的数组对象

field — 来自示例调用的 key 的值。
title — 显示在界面中的字段名称
url_field — 在此字段中指定链接的 key。请注意！第一个传递的链接将在呼叫者页面上显示为iframe，以便他们可以在不离开呼叫者页面的情况下查看项目信息。

字段可以有任意数量，但最好限制在合理的数量内，并传递到项目管理员的链接。

Apple Push Notification Service

要工作，需要指定您的应用程序的Bundle ID以及证书，或者（更简单的是）上传p12文件。

可以按照这个说明生成文件。如果您在导出时指定了密码，则在上传文件到badapush时也需要指定。

我们使用http/2协议。

Google Cloud Messaging

即Firebase Cloud Messaging。要工作，需要Firebase项目中管理界面中的“Firebase Server Key”。

说明： https://firebase.google.com/docs/cloud-messaging/auth-server#authorize-legacy-protocol-send-requests

在此阶段，我们使用的是Legacy协议。

SmsTraffic服务

为了使用，必须提供SmsTraffic账号的登录名和密码，以及需要与SmsTraffic服务端协商的发送者名称。

druidvav / badapush-client

维护者

详细信息