Ereignisbehandlung/Handler

Ereignisbehandlung bietet Ihnen die Möglichkeit bei bestimmten Ereignissen vordefinierte Aktionen auszulösen. Für einfache Signale können vordefinierte Aktionstypen wie SMS oder Email genutzt werden. Bei komplexeren Aktionen bietet Tripshare auch Webhooks an, d.h. es wird eine URL im Internet aufgerufen und via POST werden die Daten des Ereignisses übergeben.

Handler anlegen

Klicken Sie dazu bei der Handler-Übersicht auf das Symbol

Standardfelder

Jeder Handler besitzt zwei Standardfelder für Name und Description.

Geben Sie ihren Handlern einen Namen und eine Beschreibung um diese in der Übersichtsliste eindeutig identifizieren zu können.

Geräteliste

Handler werden ihren Geräten zugewiesen. Sie können dazu ein oder mehrere Geräte selektieren welche als Quelle für Ereignisse dienen.

Blättern Sie hierzu in der Liste ihrer Geräte; Sie können auch wie im Beispiel gezeigt einen Filtertext eingeben, so dass nur Geräte angezeigt werden, welche den Text enthalten. Sollten Sie nur wenige Geräte besitzen, so ist die Benutzung von Filtern meist nicht notwendig.

Ereigniscode

Mit dem Ereigniscode legen Sie fest, bei welchen Ereignissen die Aktion ausgelöst wird. In der Liste sind die Ereigniscodes der Tripshare Plattform enthalten.

Sie können aus der Liste verschiedene Codes auswählen oder auch den Eintrag - all -, welcher alle Ereignisse selektiert.

Info

Der Ereigniscode POSITION wird nur beim Handler-Typ Webhook ausgewertet. Aktionen wie EMail, SMS oder auch Telegram können sonst bei sehr kurzen Zeitintervallen den Aufruf des Hooks blockieren, da sehr schnell Quotas erreicht werden.
Der Typ WEBHOOK ist ggf nur einem höheren Tarif verfügbar! BItte wenden Sie sich an support@protegear.com

Handler Typ

Je nach Typ des Handlers können Sie verschiedene Daten eingeben

EMail

Sie können den Betreff und den Inhalt der EMail mit Hilfe von Templates erzeugen. Bitte beachten Sie, dass automatisiert erzeugte EMails oftmals in SPAM Filtern hängenbleiben können.

Sie können folgendes Template nutzen um zu Debug-Zwecken eine EMail mit allen Daten zu versenden:

{{ emoji .Event.Code}}: this is my tripsharehandler.
The device "{{.Device.Name}}" sent {{.Event.Code}}: {{.Event.IMEI}}

All:
Event: {{ printf "%+v" .Event }}
Device: {{ printf "%+v" .Device }}

JSON:
Event: {{ marshal .Event }}
Device: {{ marshal .Device }}

SMS

Info

SMS Nachrichten sind kostenpflichtig

Wird der Inhalt einer SMS dynamisch erzeugt so ist unbedingt darauf zu achten, dass der Inhalt kurz ist, da lange Texte sonst mit Hilfe von einzelnen SMS’en versendet werden und diese jeweils kostenpflichtig sind.

Telegram

Telegram unterstützt einen Subset von HTML Tags die Sie nutzen können. Es ist empfehlenswert so wenig Formatierung wie möglich zu nutzen, da bei nicht unterstützten Tags/Formaten diese Nachrichten von Telegram abgelehnt werden.

Die ChatId erhalten Sie, indem Sie in der Telegram App auf Ihrem Smartphone unseren ChatBot mit dem Namen @ProtegearBot ihrem gewünschten Chat hinzufügen. Wenn Sie noch keinen Chat haben, klicken Sie auf den obigen Link um einen Chat zu erzeugen. Ist der Bot Mitglied im Chat, so können Sie mit dem Befehl /chatid die ID des Chats erfragen. Der Bot gibt diese aus und diese ID können Sie in das angegebene Feld eintragen.

Info

Wenn Sie einen bestehenden Chat haben den Sie als Kanal nutzen wollen, so nehmen Sie bitte den @ProtegearBot als Mitglied auf. Ein Klick auf den Link erzeugt stattdessen einen neuen Chat bzw. selektiert einen bereits vorhandenen Chat zw. Ihnen und dem Bot.

Slack

Neben der Nachricht, welche Sie dynamisch erzeugen können, müssen Sie bei der Slack-Unterstützung noch die URL ihres Webhooks eingeben. Wie Sie einen solchen Webhook bei Slack anlegen, entnehmen Sie bitte der Beschreibung bei Slack.

Webhook

Ein Webhook ist eine URL die im Internet bei einem Server Ihrer Wahl terminiert. Sie können hier jede gewünschte URL angeben die Sie möchten. Um jedoch eine gewisse Sicherheit zu gewährleisten bieten sich folgende Optionen an:

• Geben Sie eine URL an, welche spezielle Paramter beinhaltet, die nur Sie kennen und die Sie an Ihrem Server überprüfen
• Geben Sie im Feld Headers Werte an, die unser System dann als HTTP-Header mit zu Ihrem Server sendet. Im Gegensatz zu URL-Parametern sind Header-Paramter normalerweise nicht in Logs zu sehen.
• Nutzen Sie einen HMAC mit einem geheimen Schlüssel. Sie können dann mit ein paar Zeilen Code prüfen, ob der bei Ihnen eingehende Request von Protegear gesendet wurde.

Sollte Ihr Server ein unsicheres Zertifikat besitzen (selfsigned), so aktivieren Sie bitte den Schalter Skip TLS Check.

Warning

Das Ausschalten des TLS Checks ist nur für Test/Entwicklung anzuraten. In produktiven Systemen sollte der Check immer aktiviert sein.

Dem Webhook werden Events übergeben. Im Gegensatz zu den anderen Handlern gibt es hier keine Templates o.ä. Stattdessen wird bei eingehenden Events der Hook aufgerufen. Es ist jedoch nicht sichergestellt, dass ein Webhook immer genau einen Event beinhaltet. Wenn viele Events vorliegen, so kann das System diese auch als Batch senden.

Webhook testen

Mit dem Knopf Send Test Message können Sie jederzeit den Webhook mit einem Dummy-Event testen.

Alternativ können Sie auch reale Daten an Ihr System senden. Selektieren Sie hierzu ein Begin- und Ende-Datum. Tripshare wird dann die Events aus diesem Zeitraum selektieren und an Ihren Webhook senden. Sie können mit Count Events vorab zählen, wieviele Events in unserer Datenbank dem Kriterium entsprechen und erst dann mit Push Events die Daten senden. Mit dem Batch limit legen Sie fest, wieviel maximale Events pro Request transportiert werden.

Handler Content

Sie können bei jedem Handler die Daten festlegen, welche übergeben werden. Dazu können Sie den Content der Nachricht mit Hilfe von Go Templates dynamisch gestalten.

Jedes Template bekommt hierzu die Daten des Events und des Geräts in den Feldern .Event sowie .Device übergeben. Da die Template-Sprache von go genutzt wird, müssen Sie für den Zugriff auf Felder diese Feldnamen kennen.

Die Datenstruktur für Device ist folgendermaßen:

type Device struct {
    ID                string              `json:"id"`
    SecondaryID       string              `json:"secondary_id"`
    Name              string              `json:"name"`
    Changed           time.Time           `json:"changed"`
    ChangedBy         string              `json:"changedBy"`
    Type              DeviceType          `json:"type"`
    Organization      string              `json:"organization"`
    Comment           string              `json:"comment"`
    ContractID        string              `json:"contractid"`
    Rate              DeviceRate          `json:"rate"`
    Firmware          string              `json:"firmware"`
    Configuration     DeviceConfiguration `json:"configuration"`
    Status            DeviceStatus        `json:"status"`
    EventLifetimeDays int                 `json:"eventLifetimeDays"`
}
type DeviceConfiguration struct {
    Activation      ActivationType `json:"activation"`
    GSM             bool           `json:"gsm"`
    Satellite       bool           `json:"satellite"`
    RescueService   bool           `json:"rescueService"`
    RescueType      RescueType     `json:"rescueType"`
    ReceiveMessages bool           `json:"receiveMessages"`
}
type DeviceRate struct {
    Active   string `json:"active"`
    Inactive string `json:"inactive"`
}
type DeviceStatus string
type ActivationType string
type RescueType string

Ein Event hat folgende Struktur:

type Event struct {
    IMEI        string           `json:"imei"`
    Sent        time.Time        `json:"sent"`
    Received    time.Time        `json:"received"`
    Code        EventCode        `json:"code"`
    DeviceCode  int              `json:"deviceCode,omitempty"`
    DeviceEvent string           `json:"deviceEvent"`
    Text        string           `json:"text,omitempty"`
    Position    *PositionInfo    `json:"position,omitempty"`
    Addresses   []string         `json:"addresses,omitempty"`
    Battery     *BatteryInfo     `json:"battery,omitempty"`
    Info        *EventInfo       `json:"info,omitempty"`
    State       *DeviceInfo      `json:"state,omitempty"`
    Crash       *CrashInfo       `json:"crash,omitempty"`
    Environment *EnvironmentData `json:"environment,omitempty"`
    Type        string           `json:"type,omitempty"`
    Source      EventChannel     `json:"source,omitempty"`
}
type PositionInfo struct {
    Invalid         bool        `json:"invalid"`
    Latitude        float64     `json:"lat"`
    Longitude       float64     `json:"lng"`
    Altitude        int         `json:"alt"`
    Height          int         `json:"height"`
    Gpsfix          int         `json:"gpsfix"`
    NumSatellites   int         `json:"numsatellites"`
    Course          int         `json:"course"`
    SpeedKmH        float64     `json:"speedkmh"`
    VerticalSpeedMs float64     `json:"verticalspeedms"`
    MotionlessSec   int         `json:"motionless"`
    HDOP            float64     `json:"hdop"`
    VDOP            float64     `json:"vdop"`
    Pos6D           *Position6D `json:"pos6d,omitempty"`
}
type BatteryInfo struct {
    LoadInPercent int     `json:"loadpercent"`
    Low           bool    `json:"low"`
    LoadVoltage   float64 `json:"loadvoltage"`
}
type EventInfo struct {
    Intervall int `json:"intervall"`
}
type DeviceInfo struct {
    SOS InfoState `json:"sos"`
}
type CrashVector struct {
    X float64 `json:"x"`
    Y float64 `json:"y"`
    Z float64 `json:"z"`
}

type CrashInfo struct {
    Acceleration []CrashVector `json:"acceleration"`
}
type EnvironmentData struct {
    Temperature *int `json:"temperature,omitempty"`
    AirPressure *int `json:"airpressure,omitempty"`
}
type Position6D string
type EventChannel string
type EventCode string