Entwickler: Aktionen und Filter

Diese Seite dokumentiert alle öffentlichen Aktionen und Filter, die in Einfache Punkte und Belohnungen (Pro) um das Verhalten zu erweitern oder mit benutzerdefiniertem Code zu integrieren.

Der auf dieser Seite zur Verfügung gestellte Code dient nur als Beispiel und sollte mit Vorsicht und nach entsprechender Prüfung verwendet werden.

---

Lebenszyklus der Kernpunkte #

Filter: spar_benutzer_punkte #

Ändern Sie den zurückgegebenen (angezeigten) Saldo für einen Benutzer.

Parameter:

• int $points Gespeicherter Saldo aus der Benutzer-Meta _spar_points.
• int 1TP4Benutzer_id

Beispiel:

add_filter( 'spar_user_points', function( $points, $user_id ) {
    // Hinzufügen eines virtuellen 100pt Vorschau-Bonus für Administratoren
    if ( user_can( $user_id, 'manage_options' ) ) {
        $points += 100;
    }
    return $points;
}, 10, 2 );

Filter: spar_update_user_points_args #

Argumente anpassen, bevor eine Punktaktualisierung durchgeführt wird.

Parameter: (int $user_id, int $points, string $action, string $note, string $action_id)

Aktion: spar_before_points_update #

Feuern Sie vor einer Aktualisierung des Gleichgewichts.

Parameter: (int $user_id, int $points, string $action, string $note, string $action_id)

Aktion: spar_after_points_update #

Feuer nach einer Balance-Aktualisierung.

Parameter: (int $user_id, int $new_balance, int $delta, string $action, string $note, string $action_id)

Aktion: spar_points_added #

Back-Compat-Haken, der beim Hinzufügen von Punkten ausgelöst wird.

Parameter: (int $user_id, int $points, string $note, string $action_id)

Aktion: spar_points_removed #

Wird ausgelöst, wenn Punkte entfernt werden.

Parameter: (int $user_id, int $points, string $note, string $action_id)

#

Filter: spar_points_history_per_page #

Steuern Sie, wie viele Protokollzeilen pro Seite im Verlauf angezeigt werden.

Parameter: (int $per_page, int $user_id)

Filter: spar_user_points_history #

Ändern Sie die zusammengestellte Antwort auf die Historie.

Parameter: (Array $result, int $user_id) wobei $result = [ 'logs' => [], 'pagination' => [] ].

Aktion: spar_user_level_changed #

Wird ausgelöst, wenn ein Benutzer in eine neue Ebene wechselt.

Parameter: (int $user_id, array $new_level, array|null $previous_level, int $lifetime_total_earned)

---

Aufträge (verdienen/abziehen) #

Filter und Aktionen für die Vergabe oder den Entzug von Punkten bei Bestellvorgängen.

• spar_bestellung_punkte_rate - Überschreiben Sie die Berechnung der Punkte pro Währungseinheit.
• spar_order_base_points - Basispunkte vor Tiers/Multiplikatoren anpassen.
• spar_order_fixed_points - Anpassung der Punkte der festen Ebene.
• spar_order_points_multiplikator - Anpassung des effektiven Multiplikators für den Auftrag.
• spar_order_awarded_points - Anpassung der für eine Bestellung vergebenen Endpunkte.
• spar_order_points_action_text - Ändern Sie die Protokollnotiz für vergebene Auftragspunkte.
• spar_before_award_order_points / spar_after_award_order_points - Vor und nach der Punktevergabe.
• spar_bestellung_punkte_abzuziehen - Stellen Sie ein, wie viele Punkte bei Erstattung oder Stornierung entfernt werden sollen.
• spar_order_deduction_action_id - Ändern Sie die für das Abzugsprotokoll verwendete Aktions-ID.
• spar_order_deduction_action_text - Protokollmeldung für Abzugsereignisse ändern.
• spar_nach_Abzug_von_Bestellpunkten - Feuer nach Abzug von Punkten aufgrund der Änderung des Auftragsstatus.

---

Einlösung & Gutscheine #

Hooks für die Einlösung von Prämien, die Erstellung von Gutscheinen und den Front-End-Einlösefluss.

• spar_vor_belohnung_wiedereinlösung - Vor der Bearbeitung einer Prämieneinlösung.
• spar_belohnung_objekt - Passen Sie das Belohnungsfeld vor der Logik an.
• spar_belohnung_kosten_punkte - Ändern Sie, wie viele Punkte erforderlich sind.
• spar_can_redeem_reward - Rücknahme zulassen oder verweigern.
• spar_belohnung_zuruecknahme_erstattet - Wird entlassen, wenn die Einlösung fehlschlägt und erstattet.
• spar_nach_belohnung_wiedereinlösung - Nach erfolgreicher Einlösung.
• spar_belohnung_gutschein_meta - Ändern Sie die Metadaten für den Gutschein.
• spar_belohnung_gutschein_erstellt - Wenn der Coupon erstellt wird.
• spar_voucher_claimed - Wenn ein Gutschein in Anspruch genommen wird.

Frontend-Integrationshaken:

• spar_before_handle_redeem_request
• spar_redeem_product_redirect_url
• spar_redeem_success_redirect
• spar_before_apply_coupon_from_query / spar_after_apply_coupon_from_query
• spar_ajax_before_apply_voucher / spar_ajax_after_apply_voucher
• spar_voucher_deferred, spar_voucher_pending_invalid, spar_voucher_auto_applied

---

E-Mails #

Generischer Haken für das Ergebnis des E-Mail-Versands, der für alle Typen gilt:

Aktion: spar_email_gesendet #

Parameter: (string $type, bool $sent, string $to, string $subject, int $user_id, string $context_id)

• $-Typ: Punkte_verdient | Gutschein_eingelöst
• $Kontext_id: Für points_earned ist dies $action_id; für voucher_claimed ist dies der gutschein_code.

Filter:

• spar_email_points_earned_subject
• spar_email_points_earned_body
• spar_email_voucher_claimed_subject
• spar_email_voucher_claimed_body

---

Ebenen #

• spar_badge_icons
• spar_alle_ebenen
• spar_user_level
• spar_user_next_level
• spar_level_fortschritt
• spar_benutzer_punkte_multiplikator

---

Mein Konto / Shortcode UI #

• spar_prämien_menu_label
• spar_account_menu_items - Endgültiges Menüfeld nach dem Einfügen filtern.
• spar_prämien_uebersicht_html
• spar_prämien_sichtbare_tabs
• spar_before_rewards_tab
• spar_nach_belohnungen_tab
• spar_render_tab_{key} - Schlüssel: verdienen, Anspruch, Ebenen, Geschichte, Gutscheine.

---

Gutscheine (Admin-Liste) #

Filter: spar_belohnung_gutschein_präfixe #

Passen Sie an, welche Gutscheincode-Präfixe in der Standard-Coupon-Liste ausgeblendet werden (z. B. Prämiengutscheine, Empfehlungsgutscheine).

Standard: [ 'Geschenk-', 'Gutschein-', 'Erstattung-' ]

---

Schnelle Beispiele #

Vergeben Sie pauschal 50 Extrapunkte auf alle abgeschlossenen Aufträge für die VIP-Rolle:

add_filter( 'spar_order_awarded_points', function( $points, $order_id, $user_id ) {
    if ( user_can( $user_id, 'vip_customer' ) ) {
        $points += 50;
    }
    return $points;
}, 10, 3 );

Sie benötigen 20% weniger Punkte, um eine Prämie am Black Friday einzulösen:

add_filter( 'spar_reward_cost_points', function( $cost, $reward, $user_id ) {
    if ( date( 'm-d' ) === '11-28' ) {
        $cost = (int) round( $cost * 0.8 );
    }
    return max( 1, $cost );
}, 10, 3 );

Ersetzen Sie den Betreff und den Text der E-Mail mit dem beanspruchten Voucher:

add_filter( 'spar_email_voucher_claimed_subject', function( $subject, $ctx ) {
    return 'Ihre Vergünstigung ist aktiviert! Code: ' . $ctx['voucher_code'];
}, 10, 2 );

add_filter( 'spar_email_voucher_claimed_body', function( $body, $ctx ) {
    return wpautop( 'Verwenden Sie Ihren Code an der Kasse, um zu sparen!' );
}, 10, 2 );

Reagiere auf Levelaufstiege:

add_action( 'spar_user_level_changed', function( $user_id, $new_level, $prev_level ) {
    // Tag in CRM, etc.
}, 10, 3

---

Funktionen #

Punkteverwaltung (programmatisch hinzufügen/entfernen) #

spar_update_user_points( int $user_id, int $points, string $action, string $note = '', string $action_id = 'custom' )

Aktualisieren Sie den Saldo eines Benutzers und fügen Sie eine Protokollzeile ein.

• $action: 'hinzufügen' oder 'entfernen'
• $note: Kurzer Text im Punkteprotokoll (bereinigt gespeichert)
• $action_id: stabiler Maschinenschlüssel für das Ereignis, zum Beispiel Bestellung_Erstattung, Anmeldung, prüfungs_bonus

Beispiele:

<?php
/**
 * 50 Punkte mit einem eindeutigen Protokollvermerk und einer benutzerdefinierten Aktionstaste hinzufügen.
 */
$user_id = get_current_user_id();
if ( $user_id ) {
    $points = absint( 50 );
    $note = sanitize_text_field( 'Promo Bonus' );
    $action_id = sanitize_key( 'promo_bonus' );

    spar_update_user_points( $user_id, $points, 'add', $note, $action_id );
}

/**
 * 30 Punkte entfernen (z.B. manuelle Admin-Anpassung).
 */
$user_id = 123;
$points = absint( 30 );
$note = sanitize_text_field( 'Manuelle Anpassung' );
$action_id = sanitize_key( 'admin_adjust' );

spar_update_user_points( $user_id, $points, 'remove', $note, $action_id );

Berechnung der Bestellpunkte (für Vorschauen/Schätzungen) #

Helfer, um die gleichen Werte zu berechnen, die das Plugin bei der Vergabe von Bestellpunkten verwendet.

Nützlich, um auf Produkt- oder Warenkorbseiten “Sie erhalten X Punkte” anzuzeigen.

spar_get_order_points_rate( string $currency_code = '' ): float

Gibt Punkte pro 1,0 Währungseinheit nach Einstellungen und Filtern zurück.

<?php
$rate = (float) spar_get_order_points_rate( get_woocommerce_currency() );

spar_calculate_order_base_points( WC_Order $order ): int

Ausgabenbasierte Punkte vor Multiplikatoren und Rängen.

<?php
$order = wc_get_order( $order_id );
$base = (int) spar_calculate_order_base_points( $order );

spar_calculate_fixed_order_points_for_total( float $total, string $currency ): array

Das Ergebnis ist auf einer festen Ebene angesiedelt:

• Punkte (int) aktuelle Stufenpunkte
• nächstes_delta (float|null) Ausgaben, die zum Erreichen der nächsten Stufe erforderlich sind
• nächste_Punkte (int|null) Punkte für die nächste Stufe

cart->get_total( 'edit' ); // Oder Ihre eigene Summe.
$info = spar_calculate_fixed_order_points_for_total( $total, get_woocommerce_currency() );
$current_points = (int) $info['points'];

Beispiel: “Sie erhalten X Punkte” auf Produktseiten

<?php
add_action( 'woocommerce_single_product_summary', function() {
    if ( ! is_user_logged_in() || empty( WC()->Wagen ) ) {
        zurück;
    }

    $currency = get_woocommerce_currency();
    $rate = (float) spar_get_order_points_rate( $currency );

    wenn ( $rate <= 0 ) {
        return;
    }

    global $product;

    $price    = (float) wc_get_price_excluding_tax( $product );
    $estimate = (int) floor( $price * $rate );

    if ( $estimate > 0 ) {
        echo '<p class="spar-estimate">' . esc_html(
            sprintf(
                __( 'Verdienen Sie ungefähr %d Punkte für diesen Artikel', 'simple-points-and-rewards' ),
                $estimate
            )
        ) . '</p>';
    }
}, 25 );

Niveaustufen-Helfer #

spar_get_user_points_multiplier( int $user_id ): float

Gibt den aktuellen stufenbasierten Multiplikator zurück, oder 1.0 wenn die Ebenen deaktiviert sind.

<?php
$multiplier = function_exists( 'spar_get_user_points_multiplier' )
    ? (float) spar_get_user_points_multiplier( get_current_user_id() )
    : 1.0;

Zuschlag/Abzug gebunden an Aufträge (manueller Auslöser) #

Das Plugin vergibt automatisch Prämien oder zieht sie bei Bestellungsereignissen ab, je nach den Einstellungen. Um die Prämienlogik manuell auszuführen:

spar_award_order_points( int $order_id ): void

Idempotent, wenn die Punkte bereits im Auftrag meta gespeichert sind.

<?php
// Mit Vorsicht zu verwenden; normalerweise durch Einstellungen und Hooks gesteuert.
spar_award_order_points( (int) $order_id );

spar_deduct_refunded_order_points( int $order_id ): void

Zieht zuvor vergebene Punkte für erstattete, stornierte oder fehlgeschlagene Bestellungen ab, sofern aktiviert.

<?php
spar_deduct_refunded_order_points( (int) $order_id );

Custom Rewards #

You can create a reward of type “Custom (Developer Hook)” in the Rewards settings tab. A custom reward lets you deduct points and then run your own logic when the customer claims it.

Fields:

• Short Description – shown to customers in the Ways to Redeem list.
• Developer Reward ID – lowercase unique identifier (letters, numbers, hyphens, underscores) you can use to distinguish multiple custom rewards.

Hook fired after successful claim and points deduction:
spar_custom_reward_claimed( $user_id, $developer_id, $reward_array, $points_spent )

Beispiel:

add_action( 'spar_custom_reward_claimed', function( $user_id, $developer_id, $reward, $points_spent ) {
  if ( 'vip_access' === $developer_id ) {
    // Grant VIP role, or set a user meta flag
    $user = get_user_by( 'ID', $user_id );
    if ( $user && ! in_array( 'vip', $user->roles, true ) ) {
      $user->add_role( 'vip' );
    }
    // Optional: notify user
    wp_mail( $user->user_email, 'VIP Access Granted', 'Enjoy your new VIP benefits!' );
  }
}, 10, 4 );

If your logic fails and you need to refund points, call:

spar_update_user_points( $user_id, $points_spent, 'add', 'Refund: custom reward failed', 'redeem_refund' );

This keeps the plugin flexible for bespoke reward types .