Wie man Metricalp mit mobilen Anwendungen integriert
Seit wir Metricalp veröffentlicht haben, haben alle immer nach Unterstützung für mobile Plattformen gefragt. Sie hatten recht, mobilbasierte Browser und direkte mobile Apps verdrängen die Webplattform. Deshalb freuen wir uns, ankündigen zu können, dass wir auf dem Weg zur Unterstützung mobiler Plattformen sind. Wir haben derzeit offizielle SDKs für React Native, Android und iOS zur Verfügung.
Vielleicht fragen Sie sich, wie es möglich ist, Metricalp mit einer mobilen App zu verwenden, ohne dass es eine offizielle Bibliothek gibt. Die Antwort ist einfach, weil Metricalp vollständig API-zentriert entwickelt wurde. Das Erstellen eines Metricalp-Ereignisses ist also einfach eine HTTP-POST-Anfrage. Dies ist der Weg im Web, mobil oder auf jeder anderen Plattform. Im Hintergrund verwenden alle Integrationsbibliotheken diese Methode, einfach indem sie eine HTTP-POST-Anfrage senden. Sie können Metricalp also auch mit Ihrer intelligenten Waschmaschine verwenden, wenn Sie dies vom ersten Tag an möchten. Hier ist die HTTP-POST-Anfrage des Ereignisses, die in der React Native-Bibliothek als Beispiel verwendet wird, und dann werden wir jeden einzelnen Aspekt davon unten beschreiben:
fetch(attributes.endpoint || Metricalp.API_ENDPOINT, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
type,
path: attributes.path || '(nicht festgelegt)',
metr_collected_via: attributes.platform,
metr_os_detail: attributes.os || '(nicht festgelegt)',
metr_app_detail: attributes.app || '(nicht festgelegt)',
metr_user_language: attributes.language || '(nicht festgelegt)',
metr_unique_identifier: attributes.uuid || '',
metr_bypass_ip: attributes.bypassIpUniqueness || false,
tid: attributes.tid,
})Das war alles. Sie können Metricalp vollständig verwenden, indem Sie die oben beschriebene HTTP-POST-Anfrage auslösen. Lassen Sie uns die Details und Tricks unabhängig von der Plattform erklären. Wir bereiten auch plattformspezifische Beispiele vor und schließlich werden wir plattformspezifische SDKs für alle Plattformen veröffentlichen. Aber bis dahin schreiben wir dieses Dokument, um Ihnen zu ermöglichen, Metricalp in Ihrer mobilen App schon jetzt zu verwenden. Außerdem können Sie mit diesem reinen HTTP-POST-Ansatz ohne ein SDK flexibler sein. Okay, fangen wir mit den Details an.
Stellen Sie sich vor, Sie müssen eine HTTP-POST-Anfrage immer wieder in Ihrer Anwendung auslösen. Diese Anfrage wird einige Standard-Eigenschaften wie Ihre Tracker-ID (tid) haben. Sie werden auch bei jedem Aufruf einige Eigenschaften definieren. Was würden Sie tun? In der Programmierung, um das DRY-Prinzip (Don't Repeat Yourself) zu schützen, erstellen Sie eine Funktion, eine Klasse oder ein Modul, um diese HTTP-POST-Anfrage zu handhaben. Hier werden wir dies tun. Wir werden eine Singleton-Klasse erstellen. Sie wird Standard-Eigenschaften speichern und eine Methode haben, um die HTTP-POST-Anfrage auszulösen. Ich werde die Singleton-Klasse der React Native-Bibliothek hier platzieren und sie daran erklären. Sie können denselben Ansatz in Java, Kotlin (Android), Objective-C, Swift (iOS) oder mit jeder anderen Plattform verfolgen.
export interface ConfigurationAttributes {
tid: string;
platform: string;
uuid: string;
os?: string;
app?: string;
language?: string;
endpoint?: string;
bypassIpUniqueness?: boolean;
}
export class Metricalp {
private static instance: Metricalp;
private static API_ENDPOINT = 'https://event.metricalp.com';
private attributes: ConfigurationAttributes | undefined = undefined;
private screenDurationStartPoint = Date.now();
private currentScreen = '';
private constructor() {}
public static getOrBuildInstance(): Metricalp {
if (!Metricalp.instance) {
Metricalp.instance = new Metricalp();
}
return Metricalp.instance;
}
public static init(
attributes: ConfigurationAttributes,
initialScreen?: string,
eventAttributes: Record<string, any> = {}
) {
const instance = Metricalp.getOrBuildInstance();
instance.setAttributes(attributes);
if (!initialScreen) {
return Promise.resolve(true);
}
return Metricalp.screenViewEvent(initialScreen, eventAttributes);
}
public static getInstance() {
if (!Metricalp.instance) {
throw new Error(
'Metricalp not initialized, please call Metricalp.init() first.'
);
}
return Metricalp.instance;
}
public setAttributes(attributes: ConfigurationAttributes) {
this.attributes = attributes;
}
public getAttributes() {
return this.attributes;
}
public getCurrentScreen() {
return this.currentScreen;
}
public setCurrentScreen(screen: string) {
this.currentScreen = screen;
}
public setScreenDurationStartPointToNow() {
this.screenDurationStartPoint = Date.now();
}
public static resetAttributes(attributes: ConfigurationAttributes) {
const instance = Metricalp.getInstance();
instance.setAttributes(attributes);
}
public static updateAttributes(attributes: ConfigurationAttributes) {
const instance = Metricalp.getInstance();
const currentAttributes = instance.getAttributes();
instance.setAttributes({ ...currentAttributes, ...attributes });
}
public static getAllAttributes() {
const instance = Metricalp.getInstance();
return instance.getAttributes();
}
public static sendEvent(
type: string,
eventAttributes: Record<string, any>,
overrideConfigurationAttributes: Partial<ConfigurationAttributes> = {}
) {
const instance = Metricalp.getInstance();
const attributes = {
...instance.getAttributes(),
...overrideConfigurationAttributes,
};
if (!attributes.tid) {
throw new Error('Metricalp Error: tid not set in Metricalp attributes.');
}
if (!attributes.platform) {
throw new Error(
'Metricalp Error: platform not set in Metricalp attributes.'
);
}
if (!attributes.uuid) {
throw new Error('Metricalp Error: uuid not set in Metricalp attributes.');
}
return fetch(attributes.endpoint || Metricalp.API_ENDPOINT, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
...eventAttributes,
type,
path: eventAttributes.path || '(not-set)',
metr_os_detail: attributes.os || '(not-set)',
metr_app_detail: attributes.app || '(not-set)',
metr_user_language: attributes.language || 'unknown-unknown',
metr_bypass_ip: attributes.bypassIpUniqueness ?? true,
metr_collected_via: attributes.platform,
metr_unique_identifier: attributes.uuid,
tid: attributes.tid,
}),
}).then((response) => {
if (!response.ok) {
return false;
}
return true;
});
}
public static screenViewEvent(
path: string,
eventAttributes: Record<string, any> = {},
overrideConfigurationAttributes: Partial<ConfigurationAttributes> = {}
) {
const instance = Metricalp.getInstance();
const prevScreen = instance.getCurrentScreen();
let screenLeaveProps = {};
if (prevScreen) {
screenLeaveProps = {
leave_from_path: prevScreen,
leave_from_duration: Date.now() - instance.screenDurationStartPoint,
};
}
instance.setCurrentScreen(path);
instance.setScreenDurationStartPointToNow();
return Metricalp.sendEvent(
'screen_view',
{ path, ...screenLeaveProps, ...eventAttributes },
overrideConfigurationAttributes
);
}
public static appLeaveEvent(
eventAttributes: Record<string, any> = {},
overrideConfigurationAttributes: Partial<ConfigurationAttributes> = {}
) {
const instance = Metricalp.getInstance();
const prevPath = instance.getCurrentScreen();
// You can not trigger leave event without a screen view event before it
if (!prevPath) {
return Promise.resolve(false);
}
const screenDuration = Date.now() - instance.screenDurationStartPoint;
instance.setScreenDurationStartPointToNow();
instance.setCurrentScreen('');
return Metricalp.sendEvent(
'screen_leave',
{
path: prevPath,
screen_duration: screenDuration,
...eventAttributes,
},
overrideConfigurationAttributes
);
}
// @deprecated No more manual session exit event
public static sessionExitEvent(
path: string,
eventAttributes: Record<string, any> = {},
overrideConfigurationAttributes: Partial<ConfigurationAttributes> = {}
) {
return Metricalp.sendEvent(
'session_exit',
{ path, ...eventAttributes },
overrideConfigurationAttributes
);
}
public static customEvent(
type: string,
eventAttributes: Record<string, any> = {},
overrideConfigurationAttributes: Partial<ConfigurationAttributes> = {}
) {
return Metricalp.sendEvent(
type,
eventAttributes,
overrideConfigurationAttributes
);
}
}
Das ist alles. Die Metricalp React Native-Bibliothek besteht aus einer einzigen Datei mit wenigen Zeilen. Das heißt, du kannst deine eigene Implementierung auf der Plattform erstellen, es ist nichts Großes. Vergiss nicht, dass es letztlich nur eine HTTP-POST-Anfrage ist.
Zunächst haben wir unsere Klasse als Singleton definiert. Weil wir Standardattribute bei der Initialisierung festlegen und nicht möchten, dass diese überschrieben werden. Diese Konzepte betreffen mehr die Programmierung als direkt Metricalp, aber es ist gut, sie hier zu erwähnen 😎.
Wir haben einige statische Eigenschaften, wie die Instanz (wegen der Singleton-Natur), API_ENDPOINT und Attribute. API_ENDPOINT ist der Endpunkt für Metricalp-Ereignisse. https://event.metricalp.com ist immer der Standardwert. Wir erlauben jedoch dem Benutzer, ihn bei Bedarf in unseren Methoden zu überschreiben (Proxy-Nutzung von Metricalp zur Umgehung von Werbeblockern usw.).
attributes ist ein Objekt (Map), um Standardattribute zu speichern. Zum Beispiel Tracker-ID (tid), aktuelle Betriebssysteminformationen, App-Version und -Name usw. Diese Daten werden mit jedem Ereignis gesendet. Wir definieren sie einmal, speichern sie in den Attributen und verwenden sie bei jedem Ereignis, um das DRY-Prinzip zu wahren. Einige Attribute müssen jedoch bei jeder Anfrage definiert werden (wie der aktuelle Pfad/Screen). Diese werden bei jeder Anfrage bereitgestellt. Schauen wir uns alle möglichen Attribute und ihre Zwecke für eine Anfrage an:
type (required)
Du solltest den Ereignistyp für jedes Ereignis angeben. Da Metricalp ein ereignisbasiertes Analysetool ist, ist es erforderlich, den Typ für jede Anfrage anzugeben. Zum Beispiel kannst du es als screen_view oder any_custom_event_name angeben.
path
Du kannst den aktuellen Bildschirm oder Pfad angeben, wenn du ein Ereignis auslöst. Es ist optional, aber empfohlen, um bessere Daten im Dashboard zu erhalten. Zum Beispiel HomePage oder SettingsPage.
metr_collected_via (required)
Du musst die aktuelle Plattform angeben. Mögliche Werte sind ios, android, web oder api. Alle müssen klein geschrieben sein. In Zukunft werden weitere Plattformen unterstützt. Dies kann einmal bei der Initialisierung definiert und in den Attributen gespeichert werden. Web bedeutet Sammlung über den Browser (erfordert den User-Agent-String in den Headern zur Informationsextraktion) und API bedeutet serverseitig erzeugte Ereignisse.
metr_os_detail
Du kannst das aktuelle Betriebssystem des Benutzers und die Version angeben. Du kannst es im Format OSName OSVersion angeben, zum Beispiel iOS 14.5 oder Android 11. Es ist optional, aber sicherlich empfohlen. Dies kann einmal bei der Initialisierung definiert und in den Attributen gespeichert werden.
metr_app_detail
Du solltest den Namen und die Version deiner App angeben. Es ist wichtig, die Version anzugeben, um detaillierte Einblicke im Dashboard zu erhalten. Du kannst es im Format AppName@Version angeben, zum Beispiel MyExampleApp@1.0.0. Es ist optional, aber sicherlich empfohlen. Dies kann einmal bei der Initialisierung definiert und in den Attributen gespeichert werden.
metr_user_language
Du solltest die aktuelle Sprache deiner App angeben. Du kannst es im Format Language (long name)-Country(ISO Code) angeben, zum Beispiel English-US oder Spanish-ES oder Turkish-TR. Wenn du dir über das Land unsicher bist, kannst du unbekannt angeben. Zum Beispiel English-unknown. Dieses Attribut kann einmal bei der Initialisierung definiert und in den Attributen gespeichert werden.
metr_unique_identifier
Wir müssen dieses Attribut metr_unique_identifier erklären. Normalerweise verwendet Metricalp beim Web-Tracking keine Cookies, wie wir an vielen Stellen erwähnt haben. Wir identifizieren Benutzer anhand ihrer IP-Adressen in Einweg-Hashes. Die Formel ist ungefähr so: hash(user_ip + user_agent + salt). Hier sind IP + user_agent fast einzigartig für jeden Benutzer. Aber bei mobilen Apps sind die User-Agent-Strings inkonsistent und nicht zuverlässig. Daher benötigen wir einen eindeutigen Identifikator für jeden Benutzer. Dies überlassen wir dir. Du kannst einen beliebigen eindeutigen Identifikator für deine App verwenden. Zum Beispiel, wenn es sich um eine Autorisierungs-App handelt und du nur nach dem Login der Benutzer verfolgst, dann kannst du Benutzer-IDs angeben. Oder du kannst gerätespezifische echte eindeutige Identifikatoren verwenden (Android und iOS haben einige native Methoden, um diese zu erhalten). Oder du kannst eine zufällige UUID generieren, wenn der Benutzer die App zum ersten Mal öffnet, diese im Speicher speichern und dann als metr_unique_identifier verwenden. Die Hashing-Algorithmen sehen dann so aus: hash(user_ip + metr_unique_identifier + salt). In diesem Ansatz bleibt die metr_unique_identifier unverändert, es sei denn, der Benutzer entfernt und installiert die App neu. Aber das ist fair genug. Wenn das nicht ausreicht, kannst du deinen eigenen eindeutigen Identifikator bereitstellen, wie oben erwähnt. Benutzer-ID oder Geräte-ID oder eine andere Kombination.
metr_bypass_ip
Dies ist ein optionales Attribut. Wenn du das oben angegebene finale Hash-Beispiel mit metr_unique_identifier siehst: hash(user_ip + metr_unique_identifier + salt), haben wir immer noch die IP in der Hash-Funktion. Wenn ein Benutzer zum Beispiel im WLAN ist und dann auf ein mobiles Netzwerk wechselt, ändert sich die IP. Während metr_unique_identifier gleich bleibt, wird die Änderung der IP als ein weiterer einzigartiger Zähler für diesen Tag gezählt. Aber du kannst diese IP-Eindeutigkeit mit diesem Attribut umgehen. Wenn du es auf true setzt, verwenden wir die IP nicht in der Hash-Funktion: hash(metr_unique_identifier + salt). Wir setzen dies standardmäßig auf true, es sei denn, der Entwickler setzt es auf falsy.
tid (required)
Du solltest deine TID (auch Tracking-ID genannt) angeben. Du kannst sie im Metricalp-Dashboard erhalten. Es ist erforderlich. Wenn du sie nicht angibst, erhältst du einen Fehler. Du findest deine TID auf der Seite Embed & Share Tracker.
[any custom props]
Du kannst mit jedem Ereignis beliebige benutzerdefinierte Eigenschaften (custom_prop1, custom_prop2...) angeben. Wenn du Aliase definiert hast, kannst du diese als Schlüssel verwenden, zum Beispiel user_id, theme usw. Du kannst Custom Event & Props für detaillierte Informationen über benutzerdefinierte Ereignisse und Eigenschaften überprüfen.
Methoden der Klasse
getOrBuildInstance()
Dies ist eine statische Methode, um die aktuelle Instanz von Metricalp zu erhalten. Wenn keine Instanz vorhanden ist, wird eine neue erstellt und zurückgegeben. Dies ergibt sich aus der Natur des Singletons.
init(attributes, initialScreen)
Metricalp.init ist eine statische Methode, die Sie einmal in Ihrer App aufrufen sollten. Sie sollte auf der obersten Ebene Ihrer App stehen. Sie werden hier die anfänglichen Attribute festlegen. Es nimmt den Pfad (Screen) als zweiten Parameter, um ihn im automatisch ausgelösten ersten scren_view-Ereignis direkt nach der Initialisierung festzulegen. Wenn Sie dieses Pfad-Argument weglassen, wird dieses automatische Triggern nicht stattfinden. Daher geben wir dem Benutzer die Möglichkeit, dieses erste automatische screen_view-Ereignis zu überspringen.
getInstance()
Metricalp.getInstance ist eine statische Methode, mit der Sie die aktuelle Instanz von Metricalp erhalten können. Sie ist nützlich, um unser Singleton-Objekt zu erhalten. Wenn noch keine Instanz erstellt wurde, wirft diese Methode einen Fehler.
setAttributes(attributes)
setAttributes ist eine Methode, um Attribute festzulegen. Wir verwenden diese Instanzmethode innerhalb anderer statischer Methoden, nachdem wir unsere Instanz erhalten haben.
getAttributes()
getAttributes ist eine Methode, um Attribute abzurufen. Wir verwenden diese Instanzmethode innerhalb anderer statischer Methoden, nachdem wir unsere Instanz erhalten haben.
resetAttributes(attributes)
resetAttributes ist eine statische Methode zum Zurücksetzen von Attributen. Sie ist nützlich, um Attribute auf einen angegebenen Anfangszustand zurückzusetzen. Sie nimmt neue Attribute als Argument.
updateAttributes(attributes)
updateAttributes ist eine statische Methode, um Attribute zu aktualisieren. Sie ist nützlich, um Attribute teilweise mit neuen zu aktualisieren. Sie nimmt neue partielle Attribute als Argument.
getAllAttributes()
getAllAttributes ist eine statische Methode, um alle Attribute abzurufen. Sie ist nützlich, um alle Attribute auf einmal zu erhalten.
sendEvent(type, eventAttributes, overrideAttributes)
sendEvent ist eine statische Methode zum Senden eines Ereignisses. Sie nimmt den Typ des Ereignisses, Ereignisattributen und Überschreibattributen (zum Überschreiben der anfänglichen Standardattribute) als Argumente. Sie kombiniert die Attribute und sendet das Ereignis mit ihnen. Sie gibt ein Versprechen zurück, das mit true aufgelöst wird, wenn das Ereignis erfolgreich gesendet wurde, andernfalls wird es mit false aufgelöst. Wir werden diese Methode nicht direkt in unserer App verwenden, wir werden screenViewEvent- und customEvent-Methoden verwenden, die Wrapper dieser Methode sind.
screenViewEvent(path, eventAttributes, overrideAttributes)
screenViewEvent ist eine statische Methode zum Senden eines screen_view-Ereignisses. Sie nimmt den Pfad des Bildschirms, Ereignisattributen und Überschreibattributen (zum Überschreiben der anfänglichen Standardattribute) als Argumente. Sie kombiniert die Attribute und sendet das Ereignis mit ihnen. Sie gibt ein Versprechen zurück, das mit true aufgelöst wird, wenn das Ereignis erfolgreich gesendet wurde, andernfalls wird es mit false aufgelöst.
appLeaveEvent(eventAttributes, overrideAttributes)
appLeaveEvent ist eine statische Methode zum Senden von screen_leave-Ereignissen. Normalerweise, wenn der Benutzer von einem Bildschirm zu einem anderen wechselt, erstellt die Bibliothek automatisch screen_leave-Ereignisse zwischen zwei screen_view-Ereignissen. Aber bei App-Verlassen (Benutzer schließt die App oder die App geht in den Hintergrund) sollten Sie es auslösen. Daher haben wir eine Methode bereitgestellt, um beim App-Verlassen auszulösen, die appLeaveEvent heißt. Sie nimmt Ereignisattributen und Überschreibattributen (zum Überschreiben der anfänglichen Standardattribute) als Argumente. Sie kombiniert die Attribute und sendet das Ereignis mit ihnen. Sie gibt ein Versprechen zurück, das mit true aufgelöst wird, wenn das Ereignis erfolgreich gesendet wurde, andernfalls wird es mit false aufgelöst.
customEvent(type, eventAttributes, overrideAttributes)
customEvent ist eine statische Methode zum Senden eines benutzerdefinierten Ereignisses. Sie nimmt den Typ des Ereignisses, Ereignisattributen und Überschreibattributen (zum Überschreiben der anfänglichen Standardattribute) als Argumente. Sie kombiniert die Attribute und sendet das Ereignis mit ihnen. Sie gibt ein Versprechen zurück, das mit true aufgelöst wird, wenn das Ereignis erfolgreich gesendet wurde, andernfalls wird es mit false aufgelöst.
Das ist alles. Sie können diesen Ansatz verfolgen und Metricalp auf jeder Plattform verwenden. Lassen Sie uns Details und Tricks unabhängig von der Plattform erklären. Wenn Sie ein React Native-Entwickler sind, können Sie die offizielle Bibliothek ohne großen Aufwand verwenden. Für andere Plattformen müssen Sie diesen Ansatz befolgen, bis wir offizielle SDKs veröffentlichen. Außerdem sind wir offen für Beiträge zu SDKs mit dem oben genannten Ansatz. Wir sind stolz darauf, API-zentriert zu sein und kein ausschließliches Web-Tool. Wir kümmern uns um alle Kunden und tun dies weiterhin auf die kostengünstigste Weise.