Wie Sie die SaveTo Wishlist Registry mit Hooks und der REST-API erweitern

Erstellen Sie eine benutzerdefinierte Integration mit Geschenkkatalogen oder ändern Sie das Verhalten von Katalogen in Ihrem Shop? SaveTo Wishlist Registry fügt PHP-Hooks und REST-API-Routen hinzu, mit denen Sie beides tun können, ohne Plugin-Dateien zu bearbeiten. Dieser Artikel listet die Routen auf, wer sie aufrufen kann, was die öffentlichen Routen zurückgeben und welche Hooks Sie verwenden können, mit funktionierenden Beispielen.

Für die Entwicklerreferenz des Basis-Plugins siehe So erweitern Sie SaveTo Wishlist mit Hooks und der REST-API.

Bevor Sie beginnen

• SaveTo Wishlist Registry (in WordPress als SaveTo Wishlist Gift Registry Addon aufgeführt) benötigt WooCommerce und SaveTo Wishlist Lite als aktive Plugins. Es ist in den Plus- und Business-Plänen enthalten und verfügt über einen eigenen Lizenzschlüssel, der von SaveTo Wishlist Pro getrennt ist.
• Jeder Hook-Name beginnt mit stwreg_. Fügen Sie Ihren Code zu einem kleinen Plugin oder zur functions.php-Datei eines Child-Themes hinzu.
• Die in diesem Artikel beschriebenen Hooks und Routen sind in SaveTo Wishlist Registry 1.0.0 vorhanden.
• Registry-Daten werden in benutzerdefinierten Tabellen gespeichert, die Ihr WordPress-Tabellenpräfix verwenden: wp_stw_registries, wp_stw_registry_items, wp_stw_registry_purchases und wp_stw_registry_contributions. Verwenden Sie die unten aufgeführten Hooks und Routen, anstatt direkt in diese Tabellen zu schreiben.

So funktioniert die REST-API

Alle Routen verwenden den Namespace saveto-wishlist-registry/v1. Auf einer Website unter https://example.com lautet die vollständige Basis-URL https://example.com/wp-json/saveto-wishlist-registry/v1/.

Routen, die einen angemeldeten Benutzer benötigen, verwenden die Standard-WordPress-REST-Authentifizierung. Senden Sie in einer Browsersitzung den Header X-WP-Nonce mit einem wp_rest-Nonce. Verwenden Sie für Server-zu-Server-Aufrufe ein WordPress-Anwendungspasswort. Öffentliche Routen erfordern keinen Login.

Die Spalte „Wer kann es aufrufen“ in den Routentabellen verwendet diese Begriffe:

• Jeder: Kein Login erforderlich.
• Angemeldeter Benutzer: Jedes angemeldete Konto.
• Registry-Besitzer: Der angemeldete Benutzer, dem die Registry in der Route gehört, oder jeder Benutzer mit der Berechtigung manage_woocommerce (standardmäßig Shop-Manager und Administratoren).
• Kaufbesitzer: Der angemeldete Benutzer, dem die Registry gehört, zu der der Kauf gehört, oder jeder Benutzer mit der Berechtigung manage_woocommerce.
• Besitzer oder Shop-Manager (registry_id): Der Besitzer der Registry, die im Abfrageparameter registry_id angegeben ist, oder ein Benutzer mit der Berechtigung manage_woocommerce. Wenn registry_id fehlt, bestehen nur Benutzer mit dieser Berechtigung.
• Shop-Manager: Ein Benutzer mit der Berechtigung manage_woocommerce.

Fehler werden als Standard-WordPress-REST-Fehler mit einem Code, einer Nachricht und einem HTTP-Status zurückgegeben. Ratenbegrenzte Anfragen geben den Status 429 mit dem Code rate_limited zurück.

REST-API-Routen

Öffentliche Routen

Die Route POST /contributions erfasst nur eine Zeile mit dem Status pending. Sie nimmt keine Zahlung entgegen. Eine Zahlungsintegration muss den Status selbst aktualisieren.

Routen des Wunschlistenbesitzers

Kauf- und Beitragsrouten

Listen-Admin-Routen

Alle Admin-Routen benötigen einen Shop-Manager.

Was die öffentlichen Routen preisgeben

Öffentliche Routen können von jedem aufgerufen werden. Prüfen Sie daher, was sie zurückgeben, bevor Sie darauf aufbauen.

GET /registry/{url_code} gibt den Registereintrag und die Landingpage-Daten in einer einzigen Antwort zurück. Sie enthält:

• Registerfelder: id, collection_id, owner_user_id, url_code, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_id, allow_fund_pooling, status, previous_url_code, created_at und updated_at.
• Anzeigefelder: title, event_type_label, event_date_iso, event_date_formatted, registrant_names, cover_image_url, cover_image_alt, is_archived, is_owner und public_url.
• Eine items Liste. Jeder Artikel enthält den Produkttitel, die Produkt-URL, das Bild, den formatierten Preis, die quantity und die purchased_quantity.

Wenn der Aufrufer der Besitzer des Registers ist oder ein Shop-Manager ist, enthält die Antwort auch eine Liste von event_types.

GET /registry/{url_code}/items gibt jeden Artikel mit seiner ID, einem product Block (ID, Variations-ID, Name, SKU, Thumbnail-URL, formatierter Preis und ob das Produkt noch existiert), quantity_wanted, quantity_purchased, quantity_remaining, is_fully_claimed, is_archived und priority zurück.

GET /registry/search gibt nur veröffentlichte Register zurück. Jedes Ergebnis enthält id, url_code, event_type, event_date, registrant_name, co_registrant_name, cover_image_id, public_url und event_date_formatted. Die Antwort enthält auch total, page und per_page.

Keine der öffentlichen Routen gibt Käufernamen, Käufer-E-Mails, Kaufzeilen, Bestell-IDs oder Beitragszeilen zurück. Diese sind nur über die Eigentümer- und Admin-Routen verfügbar. Verwenden Sie den untenstehenden stwreg_registry_data-Filter, um Felder aus der GET /registry/{url_code}-Antwort hinzuzufügen oder zu entfernen. Testen Sie Ihre Registrierungsseite, nachdem Sie ein Feld entfernt haben.

Hooks

Die folgenden Hooks sind am nützlichsten für die Erweiterung des Plugins. Die Anzahl der Argumente ist exakt. Wenn Sie einen Hook mit mehr als einem Argument hinzufügen, übergeben Sie die Anzahl der Argumente als vierten Parameter von add_filter() oder add_action().

Filter für Registrierungsdaten und die Landingpage

Geben Sie immer denselben Typ zurück, den Sie erhalten. Das Plugin wandelt den Rückgabewert in ein Array oder einen String um.

Dieses Beispiel fügt ein benutzerdefiniertes Feld zur öffentlichen Registrierungsantwort hinzu:

add_filter( 'stwreg_registry_data', function ( array $data, $row ) {
    $data['shipping_note'] = 'Gifts ship within 3 business days.';

    return $data;
}, 10, 2 );

Dieses Beispiel fügt eine Textzeile unter der Landingpage hinzu:

add_filter( 'stwreg_landing_html', function ( $html, $payload ) {
    if ( ! empty( $payload['is_archived'] ) ) {
        return $html;
    }

    return $html . '<p>' . esc_html__( 'Need help choosing a gift? Contact us.', 'your-text-domain' ) . '</p>';
}, 10, 2 );

Die Landingpage wird auch aus kleineren Abschnittsfiltern aufgebaut, einer für jeden Teil der Seite. Ihre Namen beginnen mit stwreg_landing_section_ und sie nehmen $html und $payload entgegen. Beispiele sind stwreg_landing_section_header, stwreg_landing_section_message und stwreg_landing_section_footer. Um das Aussehen der Seite ohne Code zu ändern, siehe Einstellungen für das Erscheinungsbild der Registrierungs-Landingpage.

Ratenbegrenzungsfilter

Die folgenden Routen begrenzen, wie oft ein Benutzer oder eine IP-Adresse sie aufrufen kann. Jede Grenze hat zwei Filter. Einer legt die Anzahl der Anfragen fest. Der andere legt das Zeitfenster in Sekunden fest. Jeder Filter nimmt ein Argument entgegen und muss eine Ganzzahl zurückgeben.

Das Suchlimit (30 Anfragen in 5 Minuten für jede IP-Adresse) und die Produkt- und Variationssuchlimits (60 Anfragen in 5 Minuten für jeden Benutzer) haben keinen Filter. Das Limit für den Beitragsbetrag hat seinen eigenen Filter, stwreg_contribution_max_amount (float, Standard 100000).

Dieses Beispiel erhöht das Limit für das Hinzufügen von Artikeln auf 60 Anfragen in 10 Minuten:

add_filter( 'stwreg_add_item_rate_limit', function ( $limit ) {
    return 60;
} );

add_filter( 'stwreg_add_item_rate_window', function ( $window ) {
    return 10 * MINUTE_IN_SECONDS;
} );

Standardmäßig verwendet das Plugin REMOTE_ADDR, um die IP-Adresse des Besuchers für IP-basierte Limits zu ermitteln. Wenn Ihre Website hinter einem Proxy oder CDN steht, ist REMOTE_ADDR die Proxy-Adresse, sodass alle Besucher ein Limit teilen. Verwenden Sie den Filter stwreg_trusted_ip_headers, um die Servervariablen aufzulisten, die die echte IP-Adresse enthalten. Listen Sie nur Header auf, die Ihr Proxy setzt, da Besucher die anderen fälschen können.

add_filter( 'stwreg_trusted_ip_headers', function ( array $headers ) {
    $headers[] = 'HTTP_CF_CONNECTING_IP';

    return $headers;
} );

Kaufaktionen

Das $payload Array von stwreg_after_save_purchase hat diese Schlüssel: registry_id, registry_item_id, order_id, line_item_id, quantity, buyer_name, buyer_email und status. Der Status ist recorded, voided oder refunded. Das Plugin speichert Käufe aus Bestellungen und speichert sie erneut, wenn dieselbe Bestellposition erneut verarbeitet wird. Schreiben Sie Ihren Handler so, dass er sicher zweimal für denselben Kauf ausgeführt werden kann.

add_action( 'stwreg_after_save_purchase', function ( $purchase_id, $payload ) {
    if ( 'recorded' !== $payload['status'] ) {
        return;
    }

    error_log( sprintf(
        'Registry %d: item %d bought (purchase %d).',
        $payload['registry_id'],
        $payload['registry_item_id'],
        $purchase_id
    ) );
}, 10, 2 );

Ein Registrierungsartikel kann mehr erfasste Käufe haben, als der Eigentümer angefordert hat, z. B. wenn zwei Käufer gleichzeitig auschecken. Das Plugin erlaubt dies absichtlich. Wenn dies geschieht, wird stwreg_overpurchase_recorded ausgeführt, nachdem die neue Gesamtzahl gespeichert wurde. Die Aktion kann jedes Mal erneut ausgeführt werden, wenn das Plugin einen Artikel neu berechnet, der immer noch über seiner Menge liegt. Gehen Sie also nicht davon aus, dass sie nur einmal ausgeführt wird.

add_action( 'stwreg_overpurchase_recorded', function ( $registry_item_id, $purchased_total, $requested_quantity ) {
    error_log( sprintf(
        'Registry item %d: %d bought, %d requested.',
        $registry_item_id,
        $purchased_total,
        $requested_quantity
    ) );
}, 10, 3 );

E-Mail-Filter und -Aktionen

Das Plugin sendet drei E-Mails: die Käufer-E-Mail an den Eigentümer (Typ owner_new_purchase), die Rückerstattungs-E-Mail an den Eigentümer (Typ owner_order_refund) und die E-Mail an den Administrator für neue Registrierungen (Typ admin_new_registry). Um zu ändern, was sie sagen, siehe Einrichtung von E-Mail-Benachrichtigungen für Geschenkkörbe.

Verwenden Sie den synchronen Modus, wenn WP-Cron auf Ihrer Website deaktiviert ist oder wenn Sie eine E-Mail in einer einzigen Anfrage testen möchten:

add_filter( 'stwreg_email_send_async', '__return_false' );

Wenn WP-Cron deaktiviert ist und Sie die Standardeinstellung belassen, warten E-Mails in der Warteschlange, bis ein echter Cron-Job ausgeführt wird.

Dieses Beispiel ändert den Betreff der E-Mail über einen neuen Kauf für den Eigentümer:

add_filter( 'stwreg_email_owner_new_purchase_subject', function ( $subject, $context, $payload ) {
    return 'Good news: ' . $subject;
}, 10, 3 );

Für die E-Mails an den Eigentümer enthält $context recipient, owner_display_name, registry (Zeilenobjekt), purchase (Zeilenobjekt), item (Zeilenobjekt), subject, owner_dashboard und public_url.

REST-Berechtigungsfilter

Jeder Endpunkt führt eine Berechtigungsprüfung durch, und jede Prüfung hat einen Filter. Verwenden Sie diese Filter, um den Zugriff strenger zu gestalten. Sie können den Zugriff nicht erweitern. Wenn das Plugin eine Anfrage ablehnt, kann der Filter sie nicht zulassen. Wenn das Plugin eine Anfrage zulässt, kann der Filter immer noch ein WP_Error zurückgeben, um sie abzulehnen.

Dieses Beispiel macht die Registry-Suche nur für angemeldete Benutzer verfügbar:

add_filter( 'stwreg_api_public_permissions_check', function ( $decision, $request ) {
    $search_route = '/saveto-wishlist-registry/v1/registry/search';

    if ( $search_route === $request->get_route() && ! is_user_logged_in() ) {
        return new WP_Error(
            'rest_forbidden',
            'Log in to search registries.',
            array( 'status' => 401 )
        );
    }

    return $decision;
}, 10, 2 );

Die Endpunkte /purchases/{id}/note, /purchases/{id}/thank-you und /purchases/bulk-thank-you verwenden ihre eigenen Eigentümerprüfungen und führen diese Filter nicht aus. GET /purchases und GET /contributions lassen den Registry-Besitzer ohne Filter durch. Für alle anderen führen sie die Admin-Prüfung durch, sodass stwreg_api_admin_permissions_check für sie gilt.

Andere Aktionen

Häufig gestellte Fragen

Kann ich das URL-Präfix der Registry-Seite ändern?
Ja. Der Filter stwreg_url_prefix nimmt das Präfix als String entgegen, und stwreg_registry_public_url nimmt die vollständige URL (String) und den öffentlichen Code (String) entgegen.

Wo finde ich Datenschutzexport und -löschung für Registry-Daten?
Siehe So exportieren und löschen Sie Registry-Daten für Datenschutzanfragen.

Was kommt als Nächstes?

• Wie man Geschenkkäufe einsehen und Dankesnotizen senden kann
• Wie man eine Suchseite für Geschenkkataloge einrichtet
• So richten Sie E-Mail-Benachrichtigungen für Geschenkkataloge ein

Brauchen Sie Hilfe?

Wenn Sie eine Frage haben oder auf Probleme stoßen, sind wir für Sie da.

• Premium-Benutzer: Support-Ticket eröffnen
• Kostenlose Benutzer: Besuchen Sie unser Community-Forum