技能内付费开发流程

摘要

本文主要进行技能内付费开发相关的介绍，与非付费技能一致的部分只做简单介绍，具体可以参见自定义技能创建。

创建付费技能流程

注册登录技能开放平台并完成开发者认证，以创建自定义技能为例，技能付费项选择付费，付费方式只能选择技能内付费；随后可按照技能开发流程进行平台基础信息配置、交互模型开发（用户的购买意图需要配置常用表达）、使用付费协议和bot sdk进行技能服务开发、服务部署，设备端进行付费功能的真机测试，完成测试后提交审核，审核通过后技能会成功发布到技能商店，用户可在技能中进行付费购买。

选择购买指令

DuerOS目前支持两种购买指令：Buy指令（推荐）和Charge指令。开发者可以根据需要自行选择任一指令：

• Buy指令
  • 开发者预先在DuerOS中注册商品
    • 可以自定义购买流程中涉及商品展现的相关提示
  • DuerOS负责根据商品信息完成下单，收款，并通知技能付款完成
  • 开发者可以直接调用DuerOS提供的api，获得商品列表以及用户的购买状态，降低开发成本
• Charge指令
  • 开发者自行管理商品
    • 购买流程中涉及商品展现的相关提示都为标准化配置，技能不能自行配置
  • DuerOS仅负责完成指令中指定金额的收款，并通知技能付款完成
  • 技能负责下单以及维护用户购买状态

使用Buy指令

开发者需要预先在DuerOS中注册商品。

支付流程

支付流程如下图。

用户的购买意图，需要在技能开放平台上配置相应的"常用表达"，DuerOS会带上识别的购买意图和槽位来请求技能，技能使用商品id返回Buy指令，发起付费流程。

use \Baidu\Duer\Botsdk\Directive\Pay\Buy;

$this->addIntentHandler('purchase', function(){
    $buyItem = $this->getSlot('xxx');        // 定义的槽位名称

    $productId = get_product_id($buyItem);   // 技能负责将物品转换为DuerOS的商品id
    $token = gen_token($productId);

    $buy = new Buy(
        $productId,   // 商品id
        $token,       // 自定义token
    );

    return [
        'directives' => [$buy],
        'outputSpeech' => '请支付'
    ];
});

当用户完成支付，DuerOS会发送Buy扣款事件到技能，并带上baiduOrderReferenceId参数。

$this->addEventListener('Connections.Response.Buy', function($event){
    $result = $event['payload']['purchaseResult'];

    switch ($result) {
        case 'SUCCESS':
            do_deliver();   // 给用户发放商品
            break;

        case 'ERROR_REPEAT_PURCHASE':
            do_remind();    // 用户重复购买
            break;

        default:
            handle_error(); // 其它错误
            break;
    }
});

使用Charge指令

支付流程

支付流程如下图。

用户的购买意图，需要在技能开放平台上配置相应的"常用表达"，DuerOS会带上识别的购买意图和槽位来请求技能，技能在下单时，商户服务需要产生一个订单，技能在返回的charge指令中携带sellerOrderId，发起付费流程。

use \Baidu\Duer\Botsdk\Directive\Pay\Charge;

$this->addIntentHandler("purchase", function(){
    $sellerOrderId = call_create_order();     // 到商户下单

    $charge = new Charge(
        "10.09",                        // 价格，单位：元
        "thirdpart-orderId-1121223",    // 第三方订单号
        "productName",                  // 商品名称
        "description",                  // 商品描述
    );

    return [
        'directives' => [$charge],
        'outputSpeech' => '请支付'
    ];
});

当用户完成支付，DuerOS会发送charge扣款事件到技能，并带上sellerOrderId和baiduOrderReferenceId参数。技能对应的处理如下。

$this->addEventListener('Connections.Response', function($event){
    $name = $event['name'];
    // charge 事件
    if($name == 'charge') {
        $result = $event['payload']['purchaseResult'];
        // 支付成功
        if ($result == 'SUCCESS') {
            $ret = call_order_status_update();   // 修改商户订单状态
        }
    }
});

建立商户服务

商户服务与技能通信，包括以下几种。

• 商品是否购买过
  当用户表达购买意图后，创建订单之前，应该检查当前用户是否购买过这个商品。
• 创建订单
  当用户表达购买意图后，技能应该先去商户创建一个订单，这个订单的状态可能是"待支付"，而且会有订单号。
• 订单状态修改
  当收到支付成功的事件后，技能应该通知商户，将订单的状态修改为已支付，确保用户购买了这个商品。

当用户支付成功之后，DuerOS通过charge扣款事件通知技能，技能在修改订单状态为支付成功时，应该将这些重要参数与订单一起，进行记录。

• 订单创建时间 creationTimestamp
• 百度订单号 baiduOrderReferenceId

这两个参数是后续与百度结算的重要参数。