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

Schenken

Ingame-Geschenke gestatten Spielern, Ingame-Gegenstände als Geschenke für ihre Freunde und Verwandte zu erwerben, die Spaß daran haben, ein neues Spiel auszuprobieren. Der Geschenkgeber/Spender erhält eine Quittung und die Empfänger eines Geschenks erhalten eine E-Mail mit Angaben zum Geschenk. Spieler können sich auch dafür entscheiden, ihre Identität zu verbergen, um das Geschenk anonym zu versenden. In beiden Fällen kann das Aktivieren der Funktion "Verschenken" sowohl die Einnahmen steigern als auch bestehende Nutzer dazu motivieren, das Spielen wieder aufzunehmen.

Diese Funktion bietet verschiedene Integrationsoptionen und ermöglicht es, in Spielprojekten folgende Ingame-Gegenstände als Geschenke zu verkaufen:

  • Virtuelle Währungspakete
  • Virtuelle Gegenstände
  • Spiel-Aktivierungsschlüssel

Die Option steht nur bei Projekten zur Auswahl, bei denen die Xsolla-seitige Speicherung von Benutzerdaten deaktiviert wurde. Gehen Sie zu Ihrem Kundenportal, um Benutzerdaten zu konfigurieren und zu verwalten.

Integrationsleitfaden

In Abhängigkeit der für Ihr Projekt aktivierten Module stehen folgenden Integrationsmöglichkeiten zur Verfügung:

Pay2Play-Modul

Gehen Sie folgendermaßen vor, um die Funktion zu aktivieren:

  1. Richten Sie das Pay2Play-Modul ein.
  2. Wenden Sie sich an Ihren Account Manager, um die Funktion zu aktivieren.

Module für virtuelle Gegenstände, virtuelle Währung oder die Payment Wall

Gehen Sie folgendermaßen vor, um die Funktion zu aktivieren:

  1. Richten Sie das/die jeweilige/n Modul/e für virtuelle Gegenstände, virtuelle Währung oder die Payment Wall ein.
  2. Implementieren Sie die API-Methode, um die Freundesliste an Xsolla zu übermitteln oder fügen Sie der Token-Anfrage ein Objekt mit Freundesdaten hinzu.
  3. Implementieren Sie die Handhabung des Webhook, der eine erfolgreiche Zahlung bestätigt und die Geschenkdaten enthält.
  4. Wenden Sie sich an Ihren Account Manager, um die Funktion zu aktivieren.

Modul einrichten

Um die Funktion zu aktivieren, müssen Sie das/die Modul/e für virtuelle Gegenstände, virtuelle Währung oder die Payment Wall einrichten und aktivieren.

Freundeslist in der Token-Anfrage übermitteln

Bei Bedarf können Sie der Token-Anfrage ein Array mit der Freundesliste des Benutzers hinzufügen. Wenn das Array nur einen Freund enthält, wird dieser automatisch als Geschenkempfänger identifiziert. Die Token-Anfrage darf nicht mehr als 100 Freunde enthalten. Sie können der Anfrage darüber hinaus ein Objekt mit den Geschenkdaten beifügen.

Beispiel für eine Anfrage

"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"

       }]

   }

}

Freundesliste via API übermitteln

Im vorliegenden Fall sendet Xsolla eine Anfrage bezüglich der Freundesliste an die Webhook-URL des Projekts, die in den Projekteinstellungen konfiguriert ist.

Signatur erstellen

Gehen Sie folgendermaßen vor, um eine Signatur zu erstellen:

  1. Ordnen Sie die vom Xsolla-Server empfangenen Parameter in alphabetischer Reihenfolge.
  2. Verknüpfen bzw. hängen Sie die Parameterwerte an den geheimen Schlüssel des Projekts an, der in den Projekteinstellungen generiert wurde.
  3. Wenden Sie den SHA1-Hash-Algorithmus auf den sich ergebenden String an.
  4. Übermitteln Sie das Ergebnis im 'sign'-Parameter.

Stellen Sie bei der Verarbeitung der API-Anfrage sicher, dass die empfangene Signatur mit der im 'sign'-Parameter gesendeten übereinstimmt.

Freundesliste abrufen

Beispiel für eine Anfrage

$ 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

Beispiel für eine Antwort

[
  {
  "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
  }
]

Webhooks einrichten

Achten Sie darauf, die Handhabung des Bezahl-Webhooks zu aktualisieren, da dieser ab sofort das neue gift.purchase-Objekt in seinem JSON übermittelt.

Beispiel für eine Anfrage

$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 User",
        "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"
    }
}'