Endbenutzer-Update-API-Integration

Last Updated April 14, 2023

Download as PDF

Kurzübersicht

Bei der Endbenutzer-Update-API-Integration handelt es sich um eine Integration, mit der Sie eine kundenseitige API aufrufen können, um die Endbenutzer-Attribute eines bestimmten Endbenutzers zu aktualisieren. Hiermit können serverseitige Aktualisierungsaufrufe von jedem SaaS-Dienst gesendet werden, der Callbacks an einen Endpunkt (d. h. eine URL) senden kann.

So bietet sich Ihnen die Möglichkeit, Aktualisierungen in Echtzeit für das Endbenutzerobjekt von WalkMe zu erhalten. Die eingerichtete Integration erlaubt es Ihnen, die Felder zu identifizieren, die Sie aus beliebigen Nutzdaten (Allowlist) importieren möchten, die im Endbenutzerobjekt von WalkMe gespeichert werden und später zur Filterung bei Insights, Berichterstattungen und bei der Segmentierung zur Verfügung stehen.

Anwendungsfälle

• Aktualisierung des Endbenutzerobjekts von WalkMe in Echtzeit, sobald sich ein neuer Endbenutzer registriert.
• Aktualisieren Sie das Endbenutzerobjekt von WalkMe in Echtzeit, wenn ein Endbenutzer von einem kostenlosen zu einem zahlenden Benutzer hochgestuft wird – und stellen Sie diese Daten für die Auswertung der Inhaltssegmentierung zur Verfügung.
• Aktualisieren Sie das Endbenutzerobjekt von WalkMe in Echtzeit, wenn ein Kunde abwandert.
• Richten Sie einen Webhook in Ihrem CRM ein, um das Endbenutzerobjekt von WalkMe zu aktualisieren, sobald ein Kunde eine durchschnittliche Rendite von mehr als 850.000 EUR erzielt und als „Premiumkunde“ definiert werden kann.

Erstellen einer Endbenutzer-Update-API-Integration

Schritt 1 – Erstellen Sie eine neue Endbenutzer-Update-API-Integration

1. Navigieren Sie zu Insights
2. Gehen Sie auf die Registerkarte „Integrations“ (unten links im Menü)
3. Klicken Sie auf „API to WalkMe“ – dies öffnet den Integrationsassistenten ssvs

Schritt 2 – Definieren Sie die Integration

1. Geben Sie der Integration einen Name – Bitte beachten Sie, dass dies der Name ist, der in der Rule Engine des Segmentierungszentrums des Editors sowie in Insights angezeigt wird; verwenden Sie also einen aussagekräftigen Namen.
2. Stellen Sie die „User Identifier Property“ bereit  – Geben Sie das Feld, das den „end-user identifier“ enthalten wird, als identifiziert in WalkMe an – wenn Ihre ausgewählte „End User Identifier“-Methode beispielsweise eine Variable ist, die die E-Mail des Endbenutzers enthält, sollte das angegebene Feld das Feld in den JSON-Nutzdaten sein, das die E-Mail des Endbenutzers enthalten wird. Falls Ihre Nutzdaten das Format eines JSON-Objekts haben, verwenden Sie durch Punkte getrennte Namen (<object name>.<field name>)
3. Geben Sie die Properties to Import ein – Geben Sie die Felder und ihren Typ aus den JSON-Nutzdaten an, die Sie in WalkMe importieren möchten. Dies sind die Felder, die für die Segmentierung, die Filterung auf Insights und die Berichterstattung verfügbar sein werden. Falls Ihre Nutzdaten das Format eines JSON-Objekts haben, verwenden Sie durch Punkte getrennte Namen (<object name>.<field name>). Zu den unterstützten Typen gehören: Zeichenfolgen, Zahlen, Daten (im Format JJJJ-MM-TT)
4. Klicken Sie auf Continue

Schritt 3 – Integrationsendpunkt erhalten und testen

1. Die Integration zeigt nun den Endpunkt an, an den Sie Ihre API-Anfrage senden müssen.
   

   curl -L -X POST 'https://api.walkme.com/public/v1/user/data' --header 'Content-Type: application/json' --header 'Authorization: Bearer <access-token>' --data-raw '{ "token": "c865ab9ec9ffd1fbbe18a452951329bdd3e814484086bc0068da807208062c40", "data": [ { "properties.ID": "name@company.com", "field1": "value", "field2": 123, "nested": { "field": 456 } } ] }'

2. Kopieren Sie diesen Endpunkt in den Dienst, den Sie verwenden, um WalkMe die Anfragen zu senden

Schritt 4 – Senden Sie Update-Anfragen an den Update-API-Endpunkt

Die Endbenutzer-Update-API ist über die öffentliche API von WalkMe zugänglich. Um sie zu nutzen, müssen zwei Aufrufe erfolgen

1. Ein Aufruf für „get an Authorization token“ (siehe: https://developer.walkme.com/reference#getting-started-with-your-api-1)
2. Senden Sie unter Verwendung der extrahierten Token-Autorisierung eine POST-Anfrage an den in Schritt 3 erhaltenen Endpunkt. Die Nutzdaten Ihrer Anfrage sollten mit der eingerichteten Integration übereinstimmen (siehe Beispiele unten)
   1. Der Anforderungstext muss ein gültiges Json-Objekt mit den Eigenschaften „token“ und „data“ sein.
   2. Die Eigenschaft „token“ sollte den Wert enthalten, der bei der Erstellung des Endpunkts im Integrationszentrum vergeben wurde. Sie sollte nicht mit dem „acess-token“ verwechselt werden.
   3. Die Eigenschaft „data“ ist ein aus Json-Objekten bestehender Array mit einem „User Identifier“-Feld und mindestens einem anderen Feld mit Wert („null“ ist kein gültiger Wert). Die Namen der Felder sollten mit dem Integrationsschema abgestimmt sein, so wie es bei der Einrichtung des Integrationspunktes definiert wurde.

Verwendung der Endbenutzer-Update-API für die Segmentierung

1. Nach Einrichtung der Integration – Führen Sie eine leere Veröffentlichung durch, damit Sie auf der Grundlage der importierten Felder in Ihrem Editor segmentieren können.
2. Gehen Sie im Editor von WalkMe zum Menü Manage Segments
3. Erstellen Sie ein neues oder bearbeiten Sie ein bestehendes Segment
4. In der „Rule Engine“ – wählen Sie die Gruppe „user attributes“ → wählen Sie Ihren Integrationsnamen (bereitgestellt in Schritt 2 – Definieren Sie Ihre Integration) → wählen Sie das Feld aus der Liste aus, nach der Sie segmentieren möchten
5. Definieren Sie Ihre Bedingung (beachten Sie, dass die angezeigten Operatoren durch den Typ des Feldes definiert sind, das Sie in Schritt 2 eingefügt haben – Definieren Sie Ihre Integration).
6. Klicken Sie auf „Done“.

Verwendung der Endbenutzer-Update-API für das Filtern von Daten in Insights

1. Innerhalb von Insights – erstellen Sie einen neuen oder aktualisieren Sie einen bestehenden Filter.
2. Wählen Sie „USER“ → Klicken Sie auf das Feld, das Sie in Schritt 2 importiert haben – Definieren Sie Ihre Integration. Achten Sie auf den erklärenden Text neben jedem Feld in der Liste, da Sie mehrere Felder mit demselben Namen haben können, die aus verschiedenen Integrationen stammen
3. Definieren Sie Ihre Bedingung (beachten Sie, dass die angezeigten Operatoren durch den Typ des Feldes definiert sind, das Sie in Schritt 2 eingefügt haben – Definieren Sie Ihre Integration).
4. Klicken Sie auf „Save Filter“

Bewährte Verfahren

1. Wenn Sie eine Integration modifizieren, werden die Änderungen sofort aktualisiert.
2. Sobald die Endbenutzer-Update-API aufgerufen wird, wird das Endbenutzerobjekt sofort aktualisiert. Berücksichtigen Sie, dass die Bedingungen bei jedem WM-Ladevorgang ausgewertet werden. Wenn der Endbenutzer also auf eine Schaltfläche geklickt hat, die mit einem Webhook verknüpft ist, der diesen Aufruf sendet (z. B. eine Schaltfläche zum Aktualisieren des Kontos), wird die Bedingung erst beim nächsten WM-Ladevorgang (nächste Seite oder Aktualisierung) erneut ausgewertet.
3. Weniger ist mehr – Seien Sie achtsam, was die Gesamtzahl der Attribute angeht, die Sie in WalkMe integrieren. Wir erlauben eine Gesamtzahl von 100 Attributen für alle eingehenden Integrationen.
4. Es sei darauf hingewiesen, dass die Endbenutzer-Update-API im Gegensatz zu anderen eingehenden Integrationen nur aktualisiert wird, wenn die API aufgerufen wird und auch nur für den entsprechenden Endbenutzer, mit dem die API aufgerufen wurde.
5. Wenn Sie Batchverarbeitung anwenden möchten – setzen Sie die Attribute für alle Ihre Endbenutzer im Voraus fest, sie können den Incoming Integration – CSV Upload verwenden.
   In diesem Fall ist zu beachten, dass die 2 Integrationen 2 verschiedene Attribute festlegen werden, was bedeutet, dass:
   1. Die Begrenzung von 100 Attributen für alle Integrationen gilt – sowohl für die API als auch für die eingehende Batch-Integration. Wenn also alle Felder in beiden vorhanden sind, sinkt die tatsächliche Begrenzung auf 15.
   2. Bei der Definition von Regeln für die Segmentierung müssen sie zwei Regeln aufstellen und dazwischen eine „OR“-Beziehung verwenden. Beispiel:
      Incoming Integration customer type = 'paying' OR API integration customer type = 'paying'.

Beispiel eines Prozesses

Nachfolgend finden Sie ein praktisches Beispiel für die Aktualisierung der Attribute „Customer Status“ und „Type“ auf einem WalkMe-System mit einem „Identifier“, der das Format der E-Mail des Endbenutzers hat:

Schritt 1 – Erstellen Sie eine neue Endbenutzer-Update-API-Integration

1. Navigieren Sie zu Insights
2. Gehen Sie auf die Registerkarte „Integrations“ (unten links im Menü)
3. Klicken Sie auf „API to WalkMe“ – dies öffnet den Integrationsassistenten

Schritt 2 – Definieren Sie die Integration

1. Geben Sie der Integration einen Name – „Update Customer Attributes“
2. Stellen Sie die User Identifier Property bereit – Meine WalkMe-Identifier-Methode ist eine Variable, die die E-Mail des Endbenutzers wiedergibt und meine Nutzdaten werden die E-Mail des Endbenutzers unter der Eigenschaft „E-Mail“ haben, also wähle ich: „E-Mail“.
3. Geben Sie die Properties to Import ein – Meine Nutzdaten enthalten 2 Eigenschaften, die ich importieren möchte: „Type“ und „Status“. Ich möchte diese in „Customer_Type“ und „Customer_Status“ umbenennen, damit dies die Namen der Attribute sind, die in der Segmentation Rule Engine und in Insights angezeigt werden:
   
   Beide Eigenschaften werden Werte vom Typ „String“ enthalten, weshalb ich „Property Type“ = String gewählt habe.
4. Klicken Sie auf Continue

Schritt 3 – Integrationsendpunkt erhalten

1. Die Integration zeigt nun den Endpunkt an, an den Sie Ihre API-Anfrage senden müssen.
2. Klicken Sie auf das Kopiersymbol und kopieren Sie diesen Endpunkt in den Dienst, den Sie verwenden, um WalkMe die Anfragen zu senden.

Schritt 4 – Senden Sie Update-Anfragen an den Update-API-Endpunkt, indem Sie zwei Aufrufe vornehmen

1. Get an Authorization Token (siehe: Erste Schritte mit Ihrer API im Developers Hub) Senden Sie einen POST-Aufruf an:https://api.walkme.com/accounts/connect/tokenAuthorization Type = Basic Auth (Benutzername und Kennwort sollten dem Benutzernamen und Kennwort entsprechen, die Sie für das Konto erhalten haben – siehe Voraussetzungen)Token = <access token erhalten in Schritt 4.1>Body:

   "{["grant_type" : "client_credentials"]}" An access token will be received in the response:"access_token": "eyJhbGciOiJSUzI1NiIsImtpZNURDNTY1NkU4RDc4NEUiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJhYzRpVXJXLUNZSDNHUjY3LVYzRlpXNk5lRTQifQ.eyJuYmYiOjE1Nzc2Mjk1MzYsImV4cCI6MTU3NzcxNTkzNiwiaXNzIjoiaHR0cHM6Ly9hcGkud2Fsa21lcWEuY29tL2FjY291bnRzIiwiYXVkIjpbImh0dHBzOi8vYXBpLndhbGttZXFhLmNvbS9hY2NvdW50cy9yZXNvdXJjZXMiLCJXYWxrTWUgcHVibGljIl0sImNsaWVudF9pZCI6IjdkNjhiYTUwMGQwYTExZTk4MWI4MDJlZGRhNjMiLCJqdGkiOiI4NmQyZmE1Mi00YjkxLTQyZjUtOTgxMS0wZDUxOWM4YTI1ZGMiLCJqd2siOiIzYzM4eVVwbGVrSFJHWEFoVTVKajl3Z0JBYXBBdFoyQSIsInNjb3BlIjpbImxhbmd1YWdlczpyZWFkIiwibGFuZ3VhZ2VzOndyaXRlIiwicm9sZXM6cmVhZCIsInVzZXJzOnJlYWQiLCJ1c2Vyczp3cml0ZSJdfQ.Ufmo0cR6L9LfAfFl8tE-ZwQmFS5db0IRmXeRtDw2RZ88n1yV7wJ-bHKkZcIObv90achf2-3MhSdELZPH_YJQLz858Y79szfyUi5kraX2dHfA3U7UujjuL3qEUZMK0NR5JC37RIm-tvApOrbzl0Vc4aFKSF5Ae8pBOd2zfdsTvMkczI928AFJ-ieO9-U8Pl3vrYLNjaG-WzRE111ckQzzWMf1F2svdx9VRxxLOfm8TtVatuvcAS4uQFW1XKVVAn7VLMyGJDoM6Q03UXhUsyWwtQ78wilqY2xNEM0iQS9iuDfwp5dZEzw8nrIepKBoskBGXTac8z6QQXlHfpI3Gu64YyIQc2rDyyoFFZvPNOYbV5REI6rIKpYMWvTmDXyvnON84_Ojiq0HW-ikQmMSyvHWQpS0mXDiw4x3vkwOxUIaYwQJpCILGcqgomLr7XfoqRtPz25kG2ezneCuP0WpEGsT0K2I29m0pI4HwChXOY4UeRvbTpmCWBXnfYeE8RKNClnpFGv6Vl13hvVIu42IVTXy6w8dbngf9p0L9XzwaDRXnb6apDNow49gzVidjdSw1pe2A_INGbyyNeE-mxm-rIOTeqqY5q8MK62wOeF14W3KjztHhD0q7sMhaTrXHyk3pucK6LtDsdVSFWIpGKwI6L1yBNaujDOqxuhMzkblfDB7eXUCI6IjY5Q0UyMjUyQjVCRTA5ODFGNzE5MUVCQkY5", "expires_in": 86400, "token_type": "Bearer", "scope": "languages:read languages:write roles:read users:read users:write"}

2. Senden Sie unter Verwendung des extrahierten Tokens eine POST-Anfrage an den in Schritt 3 erhaltenen Integrationsendpunkt.