App User im apiOmat modellieren

Bei der Erstellung einer neuen App steht man meist vor einer zentralen Frage: Wie modelliere ich den Nutzer meiner App? Dieser Artikel soll die Best Practices im apiOmat beschreiben und zeigen, was mit dem mitgelieferten User Modell so alles möglich ist.

Image may be NSFW.
Clik here to view.
Fertige Datenmodelle bzw. Klassen werden im apiOmat immer innerhalb von Modulen geliefert. Ein Modul ist automatisch in jeder App enthalten: Das Basics Modul. Hier wird man auch fündig, wenn man nach einem Nutzermodell sucht, nämlich in der Klasse User. Der User spiegelt eine Installation einer App wieder; er muss daher pro Gerät eindeutig sein. Beispiele hierzu findet man unter Anlegen und Laden eines neuen Users. Diese Zuordnung ist notwendig, da der User ja auch für die Authentifizierung der Requests gegen den apiOmat verwendet wird. Würde ein User für mehrere Installationen verwendet werden, wäre keine saubere Trennung der Daten möglich. Würde gar kein User verwendet, könnten nur frei zugängliche Inhalte der App abgerufen werden. Ebenso basieren viele weitere Module wie Push oder Facebook darauf, dass eine Installation der App durch einen User repräsentiert wird; die Module würden andernfalls nicht funktionieren.

Aufbau des Users

Ein User beinhaltet eine Menge von Attributen, die primär zur Authentifizierung verwendet werden:

• userName – Ein eindeutiger Name oder E-Mail Adresse für den Nutzer (obligatorisch)
• password – Das Passwort für den Nutzer (obligatorisch)
• firstName – Der Vorname des Nutzers
• lastName – Der Nachname des Nutzers
• dateOfBirth – Das Geburtsdatum des Nutzers

Wie zu sehen ist, muss bei jedem neuen Nutzer mindestens ein userName und password vergeben werden.

Ein tieferer Blick in das Modell zeigt auch ein Konstrukt namens dynamicAttributes – diese Map ist nicht beschreibbar und nur für interne Zwecke gedacht. Sie wird verwendet, um von anderen Modulen wie z.B. Push erzeugte Felder für einen Nutzer zu speichern. Fügt man beispielsweise das Push Modul hinzu, bekommt der User im SDK automatisch neue Felder, in denen die Token für das jeweilige Gerät gespeichert werden können.

Anlegen und Laden eines neuen Users

Wählt man den User im Menü links aus und wechselt zu dem Tab SDK, wird für jede Zielsprache (Javascript, iOS,…) schon ein Beispielcode angezeigt, wie ein neuer Nutzer anzulegen ist. Mit folgendem Code wird automatisch ein User angelegt, wenn er bisher noch nicht existierte:

// Create a new member/user of your app
User myUser=new User();
myUser.setUserName("johnDoe");
myUser.setPassword("1,618");

// configure datastore with user credentials
Datastore.configure( myUser );
// Try to load user or create new one if not exists
myUser.loadMeAsync(new AOMEmptyCallback() {
	@Override
	public void isDone(ApiomatRequestException exception) {
		if(exception!=null) {
			myUser.saveAsync(null);
		}
	}
} );

Der Ablauf ist immer der folgende:

1. User anlegen
2. Datastore.configure() aufrufen, damit die weitere Kommunikation mit dem Nutzernamen/Passwort des Users fortgeführt wird
3. Den vorhanden Nutzer laden (loadMe())
4. Oder: Den Nutzer speichern (save())

Wichtig ist, dass vor dem ersten Request ein Datastore.configure() aufgerufen werden muss, da sonst die Kommunikationsschicht nicht die notwendigen Informationen hat, um erfolgreich Daten mit dem apiOmat auszutauschen.

Passwort neu setzen

Während alle anderen Attribute des Users über die Setter Methoden neu gesetzt werden können, gibt es für das erneute Setzen des Passworts zwei Methoden:

• requestNewPassword() – Sendet dem User ein neues Passwort per E-Mail zu, falls das alte vergessen wurde. Hierzu ist es notwendig, dass als userName eine gültige E-Mail Adresse verwendet wurde!
• resetPassword – Setzt das Passwort auf einen neuen Wert. Ein Datastore.configure() mit dem neuen Passwort wird automatisch ausgefürt.

User erweitern

Image may be NSFW.
Clik here to view.
Häufig genügen die existierenden Attribute des Users nicht für die eigene App. Um neues Verhalten hinzuzufügen, kann man eine eigene Klasse, bspw. JiraUser im Class Editor anlegen und als Parent den User aus dem Basic Module angeben. Die eigene Klasse erbt dadurch die gesamte Funktionalität des Users und kann auch genauso zur Authentifizierung verwendet werden, wie der Beispielcode im SDK Tab bei der eigenen Klasse zeigt:

// Create a new member/user of your app
JiraUser myUser=new JiraUser();
myUser.setUserName("johnDoe");
myUser.setPassword("1,618");

// configure datastore with user credentials
Datastore.configure( myUser );
...

Rollen und Sicherheit

Eine Anmeldung mit dem User gestattet den Zugriff auf alle Attribute mit dem Recht User (und natürlich auch Guest). Ein erweitertes Rechtesystem ist aber ebenfalls möglich: Eine separate Dokumentation zur Security im apiOmat beschreibt diese komplexeren Fälle.

Abrechnung

Anhand der Verwendung des User Modells wird auch die Zahl der aktiven Nutzer berechnet, die zu Abrechnungszwecken verwendet wird. Ein aktiver Nutzer ist ein User, der innerhalb der letzten 30 Tage Requests gegen den apiOmat gestellt oder Push Nachrichten empfangen hat. Um eine korrekte Zählung zu gewährleisten ist auch daher eine korrekte Verwendung des Users notwendig (ein User = eine installierte App). Mehrfachnutzung eines Users auf mehreren Geräten wird vom System erkannt.