Vad Facebook App Events täcker i Flutter, och vad det inte gör

App Events är hur Meta får veta vad som händer inne i din app. Din app loggar en namngiven händelse, Facebook SDK buntar den och skickar den, och den syns i Events Manager. Samma händelser är vad Metas annonsrapportering tillskriver dina kampanjer.

Metas egen översikt över App Events är ett kort register snarare än en referens. Den beskriver App Events som att din app kan "track events, such as a person installing your app or completing a purchase", och länkar sedan vidare till guiderna per plattform. Kom du från den sidan för att hitta metodlistan är nästa avsnitt genvägen.

facebook_app_events täcker den ytan och bara den. Facebook Login och delning är separata SDK-komponenter och ingår inte i det här pluginet.

Det här är det mest användbara att veta om pluginet, och vad det betyder i praktiken är att du läser Metas dokumentation i stället för vår.

Pluginet speglar de nativa SDK:ernas App Events-yta 1:1. Finns en metod på AppEvents på iOS, eller på AppEventsLogger, eller bland de relaterade inställningarna i Settings och FacebookSdk på Android, så ska du hitta den här under samma namn. Ett metodnamn ur Metas nativa referens är namnet du anropar från Dart.

Metas Android-referens för AppEventsLogger är levande och direkt användbar. logEvent, logPurchase, logPushNotificationOpen, logProductItem, flush och getApplicationId är alla dokumenterade där, med de signaturer och noteringar du vill ha.

Motsvarigheten för iOS är mindre pålitlig. De referens-URL:er för FBSDKCoreKit som pluginets egna dokumentationskommentarer pekar på svarade Page Not Found när den här sidan senast kontrollerades, och Metas indexsida för iOS-referensen listade ingen post för AppEvents alls. Tills det har satt sig: läs deklarationen av AppEvents i FBSDKCoreKit direkt.

Där plattformarna verkligen skiljer sig säger pluginet det i stället för att skyla över det. clearUserDataForType fungerar på iOS och gör ingenting på Android, som loggar en varning: använd clearUserData() där.

Fyra grupper av nativa API:er är medvetet utelämnade, eftersom de inte översätts till Flutter:

• Överlagringarna av logEvent och logPurchase som tar en access token.
• Utökning av hybrid-webviews: augmentWebView och augmentHybridWebView.
• Integrationskrokarna för Unity.
• logFailedStoreKit2Purchase, som bara finns på iOS.

Hittar du inte någon av dem är den alltså borta genom ett beslut, inte genom ett förbiseende. Beslutet går att ändra: öppna ett ärende i repot och argumentera för ditt användningsfall.

Läs det här avsnittet även om du hoppar över resten.

De nativa Facebook-SDK:erna accepterar bara String och numeriska värden i händelseparametrar. En händelse som bär ett värde av någon annan typ kastas bort: tyst, utan fel, och den syns inte någonstans i Events Manager. Inte bara den felaktiga parametern. Hela händelsen.

facebook_app_events gör det misslyckandet synligt i stället:

Raden för null är den att stanna vid, eftersom det är den som inte ger något fel. Ett valfritt värde som råkar saknas lämnar tyst sin parameter utanför en händelse som i övrigt kommer fram intakt. Oftast är det vad du vill. Det är inte vad du vill när just den parametern är den du rapporterar på.

Strukturerade värden måste kodas som en JSON-sträng först, vilket är vad Meta föreskriver för parametrar som fb_content:

// Throws ArgumentError: a List is not an accepted parameter value type.
await facebookAppEvents.logEvent(
  name: 'checkout_started',
  parameters: {'fb_content': items},
);

// Correct: encode the structure as a JSON string first.
await facebookAppEvents.logEvent(
  name: 'checkout_started',
  parameters: {'fb_content': jsonEncode(items)},
);

Regeln gäller överallt där pluginet normaliserar parametrar, alltså i logEvent, logPurchase och logProductItem. Överallt där du anropar det nativa SDK:t direkt, eller loggar genom ett annat omslag, får du det nativa beteendet i stället: tystnad.

activateApp() loggar aktivering och installationshändelser. Du behöver den bara om automatisk loggning av app-händelser är avstängd eller fördröjd, vilket är det vanliga när samtycke styr initieringen. Är FacebookAutoLogAppEventsEnabled på iOS eller com.facebook.sdk.AutoLogAppEventsEnabled på Android satt till false, anropa den själv.

Du kan skicka med ett applicationId för att logga till ett annat app-id än det i din plattformskonfiguration. Den överskrivningen gäller per anrop: nästa activateApp() utan ett sådant går tillbaka till standardvärdet.

Händelser lämnar inte enheten i samma stund som du loggar dem. SDK:t lagrar dem och skickar dem i buntar. Två API:er avgör när:

• flush() skickar allt som ligger lagrat direkt. Det är vad du vill ha när du testar, så att en händelse du just utlöst når Test Events inom sekunder i stället för när nästa bunt går.
• setFlushBehavior(FlushBehavior) väljer när buntar går av sig själva. FlushBehavior.auto är SDK:ns standard: händelser skickas periodiskt och när appen läggs i bakgrunden. FlushBehavior.explicitOnly stänger av automatisk sändning, så ingenting skickas förrän du anropar flush().

explicitOnly är värd att känna till främst som orsak. En app som sätter den och sedan aldrig anropar flush() loggar händelser som aldrig lämnar enheten, och resultatet i Events Manager går inte att skilja från en app som inte loggar någonting alls. getFlushBehavior() läser tillbaka det aktuella värdet, vilket är den snabba vägen till att ta reda på vad en kodbas du har ärvt gör.

Pluginet implementerar inte ATT-dialogen, hanterar inte samtycke och gör inte att din app uppfyller integritetskraven. Inget omslag kan det. Det arbetet ligger på din app.

Det exponerar däremot SDK:ts egna integritetsinställningar, och att sätta dem rätt är också din apps uppgift. Båda halvorna är sanna, och ingen av dem ersätter den andra. Pluginet räcker dig reglagen. Sätter du ett av dem fel får du uteblivna data utan något felmeddelande.

Vilket reglage som gör vad, och varför setAdvertiserTracking är avvecklad och inte gör någonting på iOS 17 och senare, tas upp i Facebook-händelser syns inte i Events Manager.