Registrierungs-API

From Second Life Wiki
Jump to navigation Jump to search

Überblick

Die Registrierungs-API ermöglicht es Ihnen, neue Second Life Einwohner auf Ihrer Webseite anzumelden und deren Startposition festzulegen. Mit der Reg-API können Sie:

  • Ihre Community in Second Life erstellen, verwalten und verfolgen.
  • Ihre Markenidentität von der Webseite über die Registrierung bis hin zu Second Life bewahren.

Bitte beachten Sie, dass wichtige Nutzungsbeschränkungen und -bedingungen gelten. Zum Beispiel, müssen Sie klarstellen, dass die Benutzer nicht nur eine Geschäftsbeziehung mit Ihnen, sondern auch eine Geschäftsbeziehung mit Linden Lab eingehen.

Die Reg-API ist ein einfacher REST-basierter Webservice. Informationen von und an den Service werden in Form von LLSD XML-Dokumenten geliefert. Linden Lab stellt Programmbibliotheken zur Verfügung, die LLSD in Perl, PHP4 und Ruby Reg API Examples parsen und kodieren.

Was die Reg-API kann

Verwenden Sie die Reg-API, um während des Registrierungs-Prozesses Second Life-Konten auf Ihrer Webseite zu erstellen. Sie können den Registrierungsprozess an Ihre Anforderungen anpassen, um weitere Benutzerinformationen zu erfassen. Wenn ein Benutzer sich registriert, wählt dieser einen einzigartigen Second Life Namen und ein Kennwort aus. Während der Registrierung werden an Linden Lab die gleichen Daten weitergeleitet, wie auch be der Standard-Registrierung auf der Second Life-Webseite. Wenn die Registrierung abgeschlossen ist, muss Ihr Kunde den Second Life Client (Viewer) herunterladen, installieren und ausführen. Der Benutzer wird dann mit dem Konto, das auf Ihrer Webseite erstellt wurde registriert und in Second Life an der von Ihnen festgelegten Startposition starten.

Mit der Reg-API können Sie:

  • Second Life Einwohner auf Ihrer Webseite registrieren und verfolgen.
  • Einen kundenspezifischen und Ihrer Marke entsprechenden Registrierungsprozess gestalten.
  • Ihre Benutzer an eine von Ihnen ausgewählte Startposition schicken. (Beim ersten Einloggen).
  • Die Konten auf Ihrem Grundstück beschränken.
  • Falls von Linden Lab genehmigt, können Sie die Namensauswahl beschränken oder Konton mit einem kundenspezifischen Namen erstellen. Diese müssen Sie jedoch separat von Linden Lab anfordern, siehe Kundenspezifische Nachnamen für weitere Informationen.
  • Den Registrierungsprozess für Ihre Organisation nur internen Benutzern zugänglich machen. Beispielsweise über eine Intranetseite.

Was die Reg-API nicht kann

Mit der Reg-API ist es nicht möglich:

  • neue Einwohner zu Gruppen hinzuzufügen
  • Inventar anzubieten, Anhänge zu erstellen oder das Aussehen eines Einwohners zu kontrollieren.
  • Das Aussehen des Viewers verändern.
  • Die Belastung einer Region automatisch auszugleichen. Sie können jedoch mit der Reg-API die Startpositionen wahlweise variieren, basierend auf Daten aus einem LSL-Skript jeder Position.

Mit der Reg-API können Sie auch Startpositionen auf Land, das Sie nicht besitzen, festlegen. Falls Sie das Land nicht besitzen, müssen Sie jedoch vom Landbesitzer die Erlaubnis einholen, dass neue Einwohner auf seinem Land ankommen dürfen.

So können Sie teilnehmen

Um an der Beta-Phase des Registrierungs-API-Programms teilzunehmen, füllen Sie bitte das Bewerbungsformular für Registrierungs-API (en) aus. Linden Lab wird sich nach Überprüfung Ihrer Bewerbung mit Ihnen in Verbindung setzen.

Wichtige Hinweise

Um das RegAPI-Betaprogramm erfolgreich zu verwenden, sind einige technische Kenntnisse erforderlich. Leider ist es Linden Lab zu Zeit nicht möglich, technischen Kundendienst für dieses Programm anzubieten.

Reg API-Konten, über die innerhalb von 90 Tagen nach Erhalt der RegAPI-Rechte, nicht mindestens ein Konto registriert wurde, wird der Reg-API-Zugang entzogen.

Für die Teilnahme am Reg API-Programm gelten Linden Labs API-Servicebedingungen (en).

Diskussion und Kundendienst/Support

  • Bitte stellen Sie Fragen über die RegAPI auf talk page.
  • Mitglieder der RegAPI Mailingliste können hiermit Informationen und mehr über die Reg API mit anderen teilen.
  • Obwohl Linden Lab keinen Kundendienst für die Reg API anbietet, können Sie von Drittanbietern Support erwerben. Siehe Registration API Third Party Support (en).

Verwendung

Um die Reg API zu verwenden:

  1. Füllen Sie das Formular Registration API Request Form (en) aus und schicken Sie es ab. Linden Lab wird sich bei Ihnen mit einer Email melden.
  2. Verwenden Sie folgendes Formular, um Ihre Capabilities zu bestätigen Capabilities-Formular (en).
  3. Bitte vergewissern Sie sich, das der Besitzer der Region, auf welcher Ihre Benutzer inworld ankommen, Ihnen seine Zustimmung gegeben hat. Sie „müssen" über die Zustimmung verfügen (nicht für Linden Lab Orientation Islands). Falls Sie über mehrere Registrierungsprozesse verfügen und Ihre Benutzer an verschiedene Orte schicken müssen, setzen Sie sich bitte mit uns in Verbindung, damit wir die zusätzlichen Einstellungen vornehmen können.
  4. Erstellen Sie Ihre Registrierungs-Seite
  5. Falls Sie PHP verwenden, stellen Sie bitte sicher, dass die erfordlichen Libraries (php4-curl) installiert sind und funktionieren (siehe http://de.php.net/phpinfo)
  6. Testen Sie Ihren Registrierungs-Vorgang:
    • Registrieren Sie mehrere neue Benutzer.
    • Falls Fehler auftreten, überprüfen Sie bitte die Fehlercodes (en).
    • Erstellen Sie Registrierungen, um die am häufigsten auftretenden Fehlercodes zu testen und bestätigen Sie, dass Sie diese korrekt erhalten und auf diese reagieren.

WÄHREND DER TESTPHASE

Wenn Sie die RegAPI für das Hauptgrid verwenden, dann werden Benutzer unter 18 Jahren sich nicht registrieren können, da diese auf dem Hauptgrid nicht erlaubt sind. Deshalb sollten Sie zum Testen ein Geburtsdatum verwenden, das über 18 Jahre zurück liegt.

Verwenden Sie eine Email-Adresse, die zur Zeit nicht in Second Life existiert. Fall der Benutzer bereits eine Email-Adresse registriert hat, wird RegAPI-Fehlercode 95 ausgeben, was bedeutet, dass diese Email-Adresse bereits existiert. Falls Sie mit einer Fehlerfalle arbeiten, wird dieser Fehler angezeigt, ansonsten wird die Registrierung einfach fehlschlagen.

Verwendung von Capability URLs

Reg API Capabilities stehen für Zugangsrechte, mit denen bestimmte Aktionen ausgeführt werden können. Die Reg API vergibt "Capabilites" mit Capability URLs in folgender Form:

https://cap.secondlife.com/cap/0/UUID

Wobei UUID der UUID (universally unique identifier) ist, der für die bestimmte Capability vergeben wurde.

Zum Beispiel:

https://cap.secondlife.com/cap/0/2897456b-6959-473e-9b94-36d8cec1b9c3

Die Reg API vergibt Capability URLs für die folgenden Funktionen:

  • create_user - neuen Benutzer erstellen
  • check_name - gibt an, ob ein Benutzer mit einem bestimmten Second Life Vor- und Nachnamen registriert werden kann.
  • get_last_names - gibt Nachnamen und die entsprechenden IDs aus, mit denen Sie neue Benutzer registrieren können.
  • get_error_codes - gibt die Fehlercodes aus.

Weitere Informationen zu diesen Funktionen siehe Registration API Reference.

Nehmen wir zum Beispiel das Capabilities-Formular auf der Second Life-Webseite. Hierin wird eine Beschreibung der Capabilites verlangt, die Ihnen gegeben wurden.

Das Formular schickt Ihren "first_name", "last_name" und Ihr "password" an https://cap.secondlife.com/get_reg_capabilities, um Ihre Capabilities zu erhalten. Der tatsächliche HTML-Code sieht jedoch so aus:

<html4strict><form action="https://cap.secondlife.com/get_reg_capabilities" method="POST">

First Name <input name='first_name'>
Last Name <input name='last_name'>
Password <input name='password' type='password'>
 
<input type='submit' value="Get Capabilities">

</form></html4strict>

Wenn Sie ein solches Formular abschicken, dann gibt Ihnen die Reg API ein XML-Dokument zurück, das in etwas so aussieht:

<xml><llsd>

 <map>
   <key>get_error_codes</key>
   <string>https://cap.secondlife.com/cap/0/e2fd05e0-d4f0-4f04-8805-fdc1bd4e9ea2</string>
 </map>

</llsd></xml>

Dieses Beispiel zeigt, dass Sie über die Capability "get_error_codes" verfügen. Wenn Sie über andere Capabilities verfügen würden, dann würde das Dokument so aussehen:

<xml><llsd>

 <map>
   <key>create_user</key>
   <string>https://cap.secondlife.com/cap/0/35ff3b8c-a30d-4d18-b29a-e3f7f6c79cb6</string>
   
   <key>check_name</key>
   <string>https://cap.secondlife.com/cap/0/6e528ba1-a8b0-4f6b-8b56-362ee6f5cef8</string>
   
   <key>get_last_names</key>
   <string>https://cap.secondlife.com/cap/0/be4e4d2e-c00a-46cd-bb8d-d17cb8e92c9b</string>
   
   <key>get_error_codes</key>
   <string>https://cap.secondlife.com/cap/0/e75f81a5-b7da-4480-8f95-b1cf9d2d680f</string>
 </map>

</llsd></xml>

Diese Capabilities URLs sind natürlich nur als Beispiel gedacht und funktionieren nicht wirklich.

Verwendung von LLSD mit der Reg API

Mit dem LLSD XML Datenformat werden Informationen an die Capability URLs gesendet und auch von diesen angefordert. Hier ein Beispiel einer typischen LLSD XML-Nachricht:

<xml><llsd>

  <map>
    <key>dob</key>
    <string>1987-07-06</string>
    
    <key>start_region_name</key>
    <string>da boom</string>
    <key>username</key>
    <string>mistaht</string>
    <key>last_name_id</key>
    <integer>1872</integer>
    <key>password</key>
    <string>123456</string>
    <key>email</key>
    <string>ben@ben.com</string>
  </map>

</llsd></xml>

Dieses Dokument stellt ein Hashtabelle dar und enthält Keys für:

  • dob (date of birth/Geburtsdatum)
  • start_region_name
  • username
  • last_name_id
  • password
  • email

Dieses Dokument ist eine typische LLSD XML-Nachricht, die Sie eventuell an die "create_user" Capability-URL schicken, um einen neuen Benutzer einzurichten.

Die LLSD-Spezifikation beschreibt viele verschiedene Datentypen: Map, Array, String, Integer, Float, Date, und so weiter. Jeder Datentyp entspricht in den meisten Sprachen einem nativen Objekttypen.

Die LLSD XML-Bibliotheken wandeln die nativen Objekte in LLSD XML Code und umgekehrt um. Zum Beispiel, können Sie die Ruby-Bibliothek wie folgt verwenden:

require 'LLSD'

native_obj = 123
llsd_xml = LLSD.to_xml(native_obj) # Gib zurück: <llsd><integer>123</integer></llsd>
returned_native_obj = LLSD.parse(llsd_xml) # Gibt den nativen Ruby Integer 123 zurück

Falls Sie Problem mit der Typumwandlung von LLSD haben, sehen Sie sich den LLSD XML-Code an, der gesendet und empfangen wird, um das Debugging zu starten.

Konten auf einem Grundstück begrenzen

Die Reg API ermöglicht es Ihnen, die Anzahl der sich registrierenden Personen auf dem Grundstück des Kontoinhabers (Registrators) zu begrenzen. Hierzu muss bei der Kontoerstellung die Grundstücks-ID für den Parameter limited_to_estate verwendet werden. Für weitere Details siehe create_user.

So finden Sie Ihren Grundstückscode (Stand 16. März 2009):

  1. Strg-Alt-⇧ Shift-D, um das zusätzliche Pulldown-advanced menu (en) zu aktivieren.
  2. Klicken Sie auf Advanced > View Admin Options (unten in der Liste).
  3. Wählen Sie aus dem Menü Admin God Tools aus.
  4. Klicken Sie auf die Registerkarte Region. Die Grundstücks-ID wird hier angezeigt.

Konten, die keinen Zugang zum Grundstück haben

Wenn Sie die Registrierung auf "restrict to estate" (auf Grundstück beschränken) einstellen und Benutzer zu ihrem Grundstück keinen Zugang haben, kann dies daran liegen, dass Sie in der Zugangskontrolle festgelegt haben, dass Benutzer Mitglieder einer bestimmten Gruppe sein müssen, um Zugang zu erhalten. Ihre neu registrierten Benutzer werden deshalb eventuell keinen Zugang zu Ihrem Grundstück haben.

Wenn Sie den Zugang auf Gruppen beschränken möchten, müssen Sie möglicherweise das Land unterteilen, und eine Parzelle schaffen, für die keine Beschränkungen gelten. Hier sollte sich das Landegebiet befinden. Ihre Benutzer sollten dann zu der oder den Gruppen hinzugefügt werden, damit Sie Zugang zum gesamten Grundstück haben.

Richtlinien und Tipps

  • Bitte verwenden Sie das Konto, das für die Reg API zur Erstellng von Konten aktiviert wurde
  • Um zusätzliche Konten zu erstellen, müssen Sie die Registrierungs-API verwenden, nicht den Viewer oder die Registrierungsseite auf secondlife.com.
  • Bestätigen Sie, dass Sie Ihre Capabilites URL (diese bekommen Sie unter Was sind Capability URLs) mit einschließen, Ihr Konto richtig einrichten, sowie die Position im Skript.
  • Überprüfen Sie, ob Fehlercodes vorliegen
  • Treten Sie der Reg API Mailing-Liste bei, um weitere Informationen und auch Hilfe bei der Fehlerbehebung zu erhalten.

Bitte befolgen Sie folgende Richtlinien, wenn Sie Capabilites-URLs verwenden:

  • Fügen Sie Code hinzu mit dem Sie Fehlercodes erfassen und anzeigen können. Dies ist für die Fehlerbehebung hilfreich.
  • Sie sollten Ihre Capabilites-URLs nicht fest in Ihren Code einbinden. Fügen Sie diese entweder als Konstanten oder, was noch besser ist, erfassen Sie diese während der Laufzeit. Capability URLs werden irgendwann ungültig, deshalb ist es immer besser, die aktuellsten zu verwenden.
  • Halten Sie Ihre Capability-URLs geheim! Diese URLs sind nur für Ihren Gebrauch vorgesehen! Bei einer Capability-URL handelt es sich genau wie bei einem Kennwort um vertrauliche Information. Linden Lab verfolgt die Verwendung einer jeder Capability-URL.

Falls Sie PHP verwenden:

  • Die LLSD Programmbibliothek wurde nicht mit PHP5 getestet, es ist wohl bekannt, dass sie mit vielen häufig verwendeten Konfigurationen von PHP5 NICHT funktioniert. Wir hoffen sehr bald eine verbesserte Version verfügbar zu haben. Diese wird mit PHP4 und PHP5 kompatibel sein. Falls Sie in der Zwischenzeit PHP5 verwenden, einige Benutzer haben uns berichtet, dass dieser Adapter gut funktioniert: http://alexandre.alapetite.net/doc-alex/domxml-php4-php5/
  • Oder, falls Sie das Risiko lieben, versuchen Sie es mit RegAPI_for_PHP5.
  • Vergewissern Sie sich, dass die Curl-Programmbibliothek installiert ist und läuft.