Modul: Payment

Verfügbar ab Version AppServer 108571, ChatServer 108571

Mit einer Instanz von PaymentAccess kann eine App auf Aktionen zugreifen, die mit Echtgeld zu tun haben.

Die PaymentAccess-Instanz erhält man über das KnuddelsServer-Objekt mit KnuddelsServer.getPaymentAccess()

Methoden

openKnuddelShop

(
  • user
  • [transferReason]
)
asynchron

Verfügbar ab Version AppServer 20210713-180000, ChatServer 20210713-180000

Öffnet den normalen Knuddelshop beim übergebenen User. Alle gekauften Knuddel werden automatisch auf die App übertragen.

Parameter:

Beispiel:

KnuddelsServer.getPaymentAccess().openKnuddelShop(user, ' Glitzerstaub ');

requestKnuddelBuyBonusInfos

(
  • user
  • callback
)
Veraltet asynchron

Verfügbar ab Version AppServer 20200403-191108, ChatServer 20200403-191108

Veraltet: es sollte stattdessen requestKnuddelShops() genutzt werden

Ermöglicht die Abfrage von Bonus-Informationen für den Knuddel-Kauf für den angegebenen User. Der callback wird asynchron mit einer Liste der Knuddel-Kauf-Boni des Users aufgerufen. Dabei sind nur die Produkte enthalten, die einen Bonus haben. Ist die Liste leer, so hat der User keine Boni.

Die Methode hat einen Timeout von 5 Sekunden. d.h. sollte der ChatServer innerhalb von 5 Sekunden nicht antworten (üblicherweise ist es deutlich schneller), so wird der Callback mit einer leeren Bonus-Liste aufgerufen. Ebenso, falls der User nicht im Channel ist.

Parameter:

  • user User
  • callback Function

    Callback, der aufgerufen wird, um die angeforderten Bonus-Informationen zu erhalten. Der callback erhält folgende Parameter: (user: User, bonusEndTimestamp: number, bonuses: [{
    productId: string,
    origPriceCents: number,
    newPriceCents?: number,
    origKnuddelPayout: number,
    newKnuddelPayout?: number
    }], result: string)


    Der bonusEndTimestamp-Parameter enthält den Unix-Timestamp bis wann die übergebenen Boni gültig sind. Er ist 0 wenn es keine Boni gibt.

    newPriceCents und newKnuddelPayout sind optional und nur vorhanden, wenn ein entsprechender Bonus vorliegt. Um die Menge der Bonus Knuddel zu berechnen (wenn newKnuddelPayout vorhanden ist) kann folgende Formel verwendet werden: var bonusKnuddel = bonus.newKnuddelPayout - bonus.origKnuddelPayout. Für den Preisvorteil geht es analog dazu mit var discountCents = bonus.origPriceCents - bonus.newPriceCents (wenn newPriceCents vorhanden ist).

    Der result-Parameter kann folgende Werte haben:

    • "offline" = der User ist nicht im Channel (leeres Ergebnis)
    • "success" = der ChatServer hat korrekt geantwortet (korrektes Ergebnis)
    • "timeout" = der ChatServer hat nicht rechtzeitig geantwortet (leeres Ergebnis) [dies kann z.B. geschehen wenn der ChatServer überlastet ist oder ein interner Fehler auftrat - in diesem Fall bitte NICHT wiederholt erneut anfragen!]

Beispiel:

KnuddelsServer.getPaymentAccess().requestKnuddelBuyBonusInfos(user, function(user, bonusEndTimestamp, bonuses, result) {
        var logger = KnuddelsServer.getDefaultLogger();
        logger.info('Bonus for user: ' + user.getNick() + ': ' + bonuses.length);
        for (var i = 0; i < bonuses.length; i++) {
            var bonus = bonuses[i];
            logger.info('Bonus for user: ' + user.getNick() + ': '
                    + ' productId: ' + bonus.productId
                    + ', origPriceCents: ' + bonus.origPriceCents
                    + ', newPriceCents: ' + bonus.newPriceCents // kann undefined sein
                    + ', origKnuddelPayout: ' + bonus.origKnuddelPayout
                    + ', newKnuddelPayout: ' + bonus.newKnuddelPayout // kann undefined sein
                    + ', bonusEndTimestamp: ' + new Date(bonusEndTimestamp) // Bonus gültig bis
                    + ', result: ' + result // "offline", "success" oder "timeout"
            );
        }
});

requestKnuddelBuyProducts

(
  • user
  • callback
)
Veraltet asynchron

Verfügbar ab Version AppServer 20210204-140000, ChatServer 20210204-140000

Veraltet: es sollte stattdessen requestKnuddelShops() genutzt werden

Ermöglicht die Abfrage von allen verfügbaren Knuddel-Kauf-Produkten für den angegebenen User bzw. seinem aktuellen Client. Der callback wird asynchron mit einer Liste der verfügbaren Knuddel-Kauf-Produkte aufgerufen.

Die Methode hat einen Timeout von 5 Sekunden. d.h. sollte der ChatServer innerhalb von 5 Sekunden nicht antworten (üblicherweise ist es deutlich schneller), so wird der Callback mit einer leeren Produkt-Liste aufgerufen. Ebenso, falls der User nicht im Channel ist.

Parameter:

  • user User
  • callback Function

    Callback, der aufgerufen wird, um die angeforderten Produkt-Informationen zu erhalten. Der callback erhält folgende Parameter: (user: User, bonusEndTimestamp: number, products: [{
    productId: string,
    origPriceCents: number,
    newPriceCents?: number,
    origKnuddelPayout: number,
    newKnuddelPayout?: number
    }], result: string)


    Der bonusEndTimestamp-Parameter enthält den Unix-Timestamp bis wann die übergebenen Boni gültig sind. Er ist 0 wenn es keine Boni gibt.

    newPriceCents und newKnuddelPayout sind optional und nur vorhanden, wenn ein entsprechender Bonus vorliegt. Um die Menge der Bonus Knuddel zu berechnen (wenn newKnuddelPayout vorhanden ist) kann folgende Formel verwendet werden: var bonusKnuddel = bonus.newKnuddelPayout - bonus.origKnuddelPayout. Für den Preisvorteil geht es analog dazu mit var discountCents = bonus.origPriceCents - bonus.newPriceCents (wenn newPriceCents vorhanden ist).

    Der result-Parameter kann folgende Werte haben:

    • "offline" = der User ist nicht im Channel (leeres Ergebnis)
    • "success" = der ChatServer hat korrekt geantwortet (korrektes Ergebnis)
    • "timeout" = der ChatServer hat nicht rechtzeitig geantwortet (leeres Ergebnis) [dies kann z.B. geschehen wenn der ChatServer überlastet ist oder ein interner Fehler auftrat - in diesem Fall bitte NICHT wiederholt erneut anfragen!]

Beispiel:

KnuddelsServer.getPaymentAccess().requestKnuddelBuyProducts(user, function(user, bonusEndTimestamp, products, result) {
        var logger = KnuddelsServer.getDefaultLogger();
        logger.info('Products for user: ' + user.getNick() + ': ' + products.length);
        for (var i = 0; i < products.length; i++) {
            var product = products[i];
            logger.info('Product for user: ' + user.getNick() + ': '
                    + ' productId: ' + product.productId
                    + ', origPriceCents: ' + product.origPriceCents
                    + ', newPriceCents: ' + product.newPriceCents // kann undefined sein
                    + ', origKnuddelPayout: ' + product.origKnuddelPayout
                    + ', newKnuddelPayout: ' + product.newKnuddelPayout // kann undefined sein
                    + ', bonusEndTimestamp: ' + new Date(bonusEndTimestamp) // Bonus gültig bis
                    + ', result: ' + result // "offline", "success" oder "timeout"
            );
        }
});

requestKnuddelShops

(
  • user
  • callback
)
asynchron

Verfügbar ab Version AppServer 20210215-140000, ChatServer 20210215-140000

Ermöglicht die Abfrage von allen verfügbaren KnuddelShops für den angegebenen User bzw. seinem aktuellen Client. Der callback wird asynchron mit einer Liste der verfügbaren KnuddelShops aufgerufen.

Die Methode hat einen Timeout von 5 Sekunden. d.h. sollte der ChatServer innerhalb von 5 Sekunden nicht antworten (üblicherweise ist es deutlich schneller), so wird der Callback mit einer leeren Shop-Liste aufgerufen. Ebenso, falls der User nicht im Channel ist.

Parameter:

  • user User
  • callback Function

    Callback, der aufgerufen wird, um die angeforderten Produkt-Informationen zu erhalten. Der callback erhält folgende Parameter: (user: User, bonusEndTimestamp: number, shops: KnuddelShop[], result: string)

    Der bonusEndTimestamp-Parameter enthält den Unix-Timestamp bis wann die übergebenen Boni gültig sind. Er ist 0 wenn es keine Boni gibt.

    Die Attribute newPriceCents und newKnuddelPayout der KnuddelShopProducts der KnuddelShops sind optional und nur != null, wenn ein entsprechender Bonus vorliegt. Um die Menge der Bonus Knuddel zu berechnen (wenn newKnuddelPayout != null ist) kann folgende Formel verwendet werden: let bonusKnuddel = product.getNewKnuddelPayout() - product.getOrigKnuddelPayout(). Für den Preisvorteil geht es analog dazu mit let discountCents = product.getOrigPriceCents() - product.getNewPriceCents() (wenn newPriceCents != null ist).

    Der result-Parameter kann folgende Werte haben:

    • "offline" = der User ist nicht im Channel (leeres Ergebnis)
    • "success" = der ChatServer hat korrekt geantwortet (korrektes Ergebnis)
    • "timeout" = der ChatServer hat nicht rechtzeitig geantwortet (leeres Ergebnis) [dies kann z.B. geschehen wenn der ChatServer überlastet ist oder ein interner Fehler auftrat - in diesem Fall bitte NICHT wiederholt erneut anfragen!]

Beispiel:

KnuddelsServer.getPaymentAccess().requestKnuddelShops(user, function(user, bonusEndTimestamp, shops, result) {
        const logger = KnuddelsServer.getDefaultLogger();
        logger.info('Shops for user: ' + user.getNick() + ': ' + shops.length
                    + ', bonusEndTimestamp: ' + new Date(bonusEndTimestamp) // Bonus gültig bis
                    + ', result: ' + result // "offline", "success" oder "timeout"
        );
        for (let i = 0; i < shops.length; i++) {
            let shop = shops[i];
            logger.info('Shopname: ' + shop.getShopName());
            let products = shop.getProducts();
            logger.info('Products for shop: ' + products.length);
            for (let j = 0; j < products.length; j++) {
                let product = products[j];
                logger.info('Product for user: ' + user.getNick() + ': '
                            + ' productId: ' + product.getProductId()
                            + ', origPriceCents: ' + product.getOrigPriceCents()
                            + ', newPriceCents: ' + product.getNewPriceCents() // kann null sein
                            + ', origKnuddelPayout: ' + product.getOrigKnuddelPayout()
                            + ', newKnuddelPayout: ' + product.getNewKnuddelPayout() // kann null sein
                );
            }
        }
    });

startKnuddelPurchase

(
  • user
  • amount
  • [parameters]
)

Verfügbar ab Version AppServer 108571, ChatServer 108571

Veraltet: es sollte stattdessen die Methode startKnuddelPurchase() , der eine productId statt einer KnuddelAmount übergeben wird, verwendet werden.

Öffnet für den angegebenen User den Kauf-Dialog "Knuddel-Direktkauf für Euros" entsprechend dem angegebenen Knuddel-Betrag. Gibt es kein Produkt, welches diesem Betrag genau entspricht, so wird das nächst höhere (bzw. das höchste) Produkt genommen. Die Aktion ist nur erlaubt, wenn der User im App-Channel online ist.

Die Methode wirft Exceptions:

  • bei fehlendem User
  • fehlendem oder ungültigem KnuddelAmount Wert
  • wenn die customMessage oder der transferReason zu lang ist
  • wenn der User nicht im Channel online ist

Darüber hinaus gibt es kein Feedback, ob die Aktion erfolgreich war, ausser der User kauft ein Produkt und transferriert die Knuddel zur App / zum Account, wobei die üblichen Hooks aufgerufen werden (jenachdem, was die App implementiert hat und welcher Modus [Parameter: toAccount] verwendet wird):

Parameter:

  • user User
  • amount KnuddelAmount

    Erlaubte Werte: 1 bis 100.000 (das größte Produkt ist aktuell 50.000 Knuddel)

  • [parameters] Object optional
    • [customMessage] String optional

      Nachricht zur Anzeige im Kaufdialog (z.B. "Du hast nicht genug Knuddel um teilzunehmen!"). Einfacher Text. Hier ist keinerlei Formatierung möglich. Limit: 200 Zeichen.

    • [transferReason] String optional

      transferReason für den /appknuddel-Transfer nach dem Kauf. Der transferReason wird ebenfalls in /knuddelaccount des Users angezeigt. Default: "Knuddel-Kauf". Limit: 200 Zeichen.

    • [toAccount] Boolean optional

      Steuert den Transfer der gekauften Knuddel zur App: (Default: false)

      • Wenn true, dann wird der angegebene Knuddel-Betrag nach dem Kauf automatisch und ohne Bestätigung auf den KnuddelAccount des Users übertragen. Dies geschieht unabhängig davon, ob die App den onBeforeKnuddelReceived-Hook implementiert hat. Nach dem Transfer wird onAccountReceivedKnuddel aufgerufen. Der User erhält zusätzlich eine Nachricht, dass seine gekauften Knuddel nun auf seinem Account sind.
      • Wenn false, dann wird nach dem Kauf /appknuddel APP-BOT:AMOUNT:TRANSFER-REASON gestartet. Dabei wird dem User das übliche /appknuddel-Bestätigungs-Popup angezeigt.

Beispiel:

KnuddelsServer.getPaymentAccess().startKnuddelPurchase(user, new KnuddelAmount(100), {
            customMessage: 'Du hast nicht genug Knuddel für den Glitzerstaub.', // optional
            transferReason: 'Glitzerstaub', // optional
            toAccount: false // optional
});

startKnuddelPurchase

(
  • user
  • productId
  • [parameters]
)

Verfügbar ab Version AppServer 20210315-162600, ChatServer 20210315-162600

Öffnet für den angegebenen User den Kauf-Dialog "Knuddel kaufen" entsprechend der übergebenen productId. Gibt es kein Produkt, welches der productId entspricht, so wird ein 9,99 Euro Produkt gewählt.

Die Aktion ist nur erlaubt, wenn der User im App-Channel online ist.

Die Methode wirft Exceptions:

  • bei fehlendem User
  • fehlender productId
  • wenn die customMessage oder der transferReason zu lang ist
  • wenn der User nicht im Channel online ist

Darüber hinaus gibt es kein Feedback, ob die Aktion erfolgreich war, ausser der User kauft ein Produkt und transferriert die Knuddel zur App / zum Account, wobei die üblichen Hooks aufgerufen werden (jenachdem, was die App implementiert hat und welcher Modus [Parameter: toAccount] verwendet wird):

Parameter:

  • user User
  • productId String
  • [parameters] Object optional
    • [customMessage] String optional

      Nachricht zur Anzeige im Kaufdialog (z.B. "Du hast nicht genug Knuddel um teilzunehmen!"). Einfacher Text. Hier ist keinerlei Formatierung möglich. Limit: 200 Zeichen.

    • [transferReason] String optional

      transferReason für den /appknuddel-Transfer nach dem Kauf. Der transferReason wird ebenfalls in /knuddelaccount des Users angezeigt. Default: "Knuddel-Kauf". Limit: 200 Zeichen.

    • [toAccount] Boolean optional

      Steuert den Transfer der gekauften Knuddel zur App: (Default: false)

      • Wenn true, dann wird der angegebene Knuddel-Betrag nach dem Kauf automatisch und ohne Bestätigung auf den KnuddelAccount des Users übertragen. Dies geschieht unabhängig davon, ob die App den onBeforeKnuddelReceived-Hook implementiert hat. Nach dem Transfer wird onAccountReceivedKnuddel aufgerufen. Der User erhält zusätzlich eine Nachricht, dass seine gekauften Knuddel nun auf seinem Account sind.
      • Wenn false, dann wird nach dem Kauf /appknuddel APP-BOT:AMOUNT:TRANSFER-REASON gestartet. Dabei wird dem User das übliche /appknuddel-Bestätigungs-Popup angezeigt.

Beispiel:

KnuddelsServer.getPaymentAccess().startKnuddelPurchase(user, 'productId', {
            customMessage: 'Du hast nicht genug Knuddel für den Glitzerstaub.', // optional
            transferReason: 'Glitzerstaub', // optional
            toAccount: false // optional
});