The following documentation was deprecated. Current version is available at developers.xsolla.com

赠送礼物

通过游戏的送礼功能,玩家可购买游戏商品作为礼物,将其赠送给爱好尝试新游戏的朋友及家人。送礼人将收到凭证,收礼人将收到包含礼物信息的电子邮件。此外,送礼人可选择隐藏身份,匿名送出礼物。无论哪种情况,启用送礼功能均可提高再次参与度和边际收益。

此功能提供多种集成选项,支持游戏项目选择以下游戏商品作为礼物销售:

  • 虚拟货币套餐
  • 虚拟物品
  • 游戏激活密钥

该选项仅适用于已禁用Xsolla侧用户数据存储的项目。请转到您的发布商帐户配置及管理用户数据存储设置。

集成指南

根据项目启用的模块不同,有以下集成选项可供选择:

Pay2Play模块

若要启用该功能,请执行以下操作:

  1. 设置Pay2Play模块。
  2. 要启用该功能,请联系您的帐户经理。

虚拟物品、虚拟货币或Payment Wall模块

若要启用该功能,请执行以下操作:

  1. 分别设置虚拟物品虚拟货币Payment Wall模块。
  2. 通过实现API方法将好友列表发送给Xsolla,或将包含好友数据的对象添加到令牌请求。
  3. 实现webhook处理,该webhook可发送成功付款确认,并包含礼物数据。
  4. 要启用该功能,请联系您的帐户经理。

设置模块

要启用该功能,必须已设置并启用虚拟物品、虚拟货币或Payment Wall模块。

在令牌请求中发送好友列表

如有必要,可将包含用户好友列表的数组添加到令牌请求。如果数组中只包含一位好友,则自动将其识别为收礼人。令牌请求中的好友数最大为100。此外,还可在请求中添加一个包含礼物数据的对象。

请求示例

"purchase":{

   "virtual_currency":{

       "quantity":100

   },

   "description":{

       "value":"Test Purchase"

   },

   "gift":{

       "giver_id":"John Smith",

       "message":"GG WP",

       "hide_giver_from_receiver" : true,

       "friends":[

       {

        "id": "123",

        "name": "captain",

        "email": "captain@ship.com"

       }]

   }

}

通过API发送好友列表

该情况下,Xsolla将向项目的webhook URL(在项目设置中配置)发送一个好友列表请求

创建签名

若要创建签名,请执行以下操作:

  1. 将从Xsolla服务器收到的参数按字母顺序排序。
  2. 连接参数值和项目设置中生成的项目密钥。
  3. 使用SHA1算法对结果字符串进行散列。
  4. 将结果包含在'sign'参数中发送。

处理API请求时,请确保收到的签名与'sign'参数中发送的签名一致。

获取好友列表

请求示例

$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
- X GET \
- u merchant_id:merchant_api_key

响应示例

[
  {
  "friends":[
      {
        "id": "1",
        "name": "John Carter",
        "email": "carter@xsolla.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "John Smith",
        "email": "smith@xsolla.com",
        "image_url": "https://partner/link/cook.jpg"
      }
    ],
  "total": 10
  }
]

设置Webhook

请确保更新支付webhook的处理,该webhook将在其JSON中传递新 gift.purchase对象。

请求示例

$curl -v 'https://your.hostname/your/uri' \
- X POST \
- d '{
    "notification_type":"payment",
    "purchase":{
        "virtual_currency":{
            "name":"Coins",
            "sku":"test_package1",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id": "Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency":"USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku":"test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "gift":{
             "giver_ID":"John Smith",
             "receiver_ID":"Ivan Ivanov",
             "receiver_email":"example@example.com",
             "message":"GG WP",
             "hide_giver_from_receiver": true
        },
        "total":{
            "currency":"USD",
            "amount":200
        },
        "promotions":[{
            "technical_name":"Demo Promotion",
            "id":"853"
        }],
        "coupon":{
             "coupon_code":"ICvj45S4FUOyy",
             "campaign_code":"1507"
        }
    },
    "user":{
        "ip":"127.0.0.1",
        "phone":"18777976552",
        "email":"email@example.com",
        "id":"1234567",
        "name":"Xsolla 用户",
        "country":"US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "payment_date":"2014-09-24T20:38:16+04:00",
        "payment_method":1,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat":{
            "currency":"USD",
            "amount": 0
        },
        "payout_currency_rate":1,
        "payout":{
            "currency":"USD",
            "amount":200
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount":10
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":20
        }
    },
    "custom_parameters":{
        "parameter1":"value1",
        "parameter2":"value2"
    }
}'