Blackout is the codename for the Farfetch Platform Solutions (FPS) projects. Useful to build e-commerce applications using the FPS APIs and integrating business logic.
To make the analytics API more consistent and easier to understand.
Describe the solution you'd like
Lifecycle events
The Integration class method setConsent should be renamed to onSetConsent to be consistent with onSetUser method.
The loadIntegration event type should be dropped in favour of the onSetUser event that should be called automatically by analytics if the user was set in analytics through the analytics.setUser method.
Analytics
Change analytics.user method to analytics.getCurrentUserData. CurrentUser was chosen to clear some ambiguity that analytics.user could bring as, without looking at the documentation of its only argument, we could think that this function accepts a user id and retrieves the instance of the user associated with that id. Also, this name makes it clear it will only get the data that was set and not a user instance that can manipulate the user data.
Change analytics.consent method to analytics.getConsentData. Same reasoning as the one used in analytics.getCurrentUserData except that there was no need to use 'current' in the name as there is no ambiguity in that case.
Change analytics.context method to analytics.getContextData (same reasoning as explained before)
Change analytics.integration method to analytics.getIntegrationInstance to make it clear that it will return the fully instantiated instance of the integration associated with its name argument.
There can also be some ambiguity regarding the names of the analytics.setUser and analytics.setConsent methods as we could imply by their names that the previous set values are completely overridden by the values passed on the call to these methods. However, that is not the case as they are only merged with the previous values. For example, if a call to setUser method is made with 10 as the userId and { isGuest: true, email: test@test.com } as its properties and then another call is made to setUser with 20 as the userId and { isGuest: false }, it could be expected that the email property would be dropped, which is not the case. However, other analytics libraries that have the same nomenclature (ga/firebase set methods for example) works the same way, so it is ok to keep using the same names, while also documenting this behaviour and indicating alternative methods to clear all the data. For setUser we have the anonymize method but for setConsent there is nothing available that clears all data, so it might make sense to add one as well.
Describe alternatives you've considered
About the loadIntegration event type, there are some integrations that access it to get other data set in analytics. However, none of them is looking at the loadIntegration event type specifically. They are either accessing the context or consent variables, which probably means that the loadData parameter is used not as an event but as a shortcut to get some analytics values, so we could ditch the event property altogether from the loadData parameter as it is not an event per see.
Regarding the changes for analytics.user, analytics.consent and analytics.integration method names, maybe there is no need to have such verbose method names. Since we'll not change what data they return, it will continue to be clear for the developers what these methods are for, and we could simplify the naming a bit by just adding the prefix get{MethodName}, to match the opposite methods we have that have the prefix set{MethodName} for setting those values.
Additional information
Decision log 19 Feb:
Lifecycle events must have a signature like @onIntegrationInit both for the type and for event (and export these constants for reusability);
Getters and setters follow the same rule: get{MethodName} and set{MethodName}. (addIntegration will continue the same, but the getter will be changed to getIntegration);
Is your proposal related to a problem?
To make the analytics API more consistent and easier to understand.
Describe the solution you'd like
Lifecycle events
The
Integration
class methodsetConsent
should be renamed toonSetConsent
to be consistent withonSetUser
method. TheloadIntegration
event type should be dropped in favour of theonSetUser
event that should be called automatically by analytics if the user was set in analytics through theanalytics.setUser
method.Analytics
analytics.user
method toanalytics.getCurrentUserData
. CurrentUser was chosen to clear some ambiguity thatanalytics.user
could bring as, without looking at the documentation of its only argument, we could think that this function accepts a user id and retrieves the instance of the user associated with that id. Also, this name makes it clear it will only get the data that was set and not a user instance that can manipulate the user data.analytics.consent
method toanalytics.getConsentData
. Same reasoning as the one used inanalytics.getCurrentUserData
except that there was no need to use 'current' in the name as there is no ambiguity in that case.analytics.context
method toanalytics.getContextData
(same reasoning as explained before)analytics.integration
method toanalytics.getIntegrationInstance
to make it clear that it will return the fully instantiated instance of the integration associated with its name argument.analytics.setUser
andanalytics.setConsent
methods as we could imply by their names that the previous set values are completely overridden by the values passed on the call to these methods. However, that is not the case as they are only merged with the previous values. For example, if a call tosetUser
method is made with10
as theuserId
and{ isGuest: true, email: test@test.com }
as itsproperties
and then another call is made tosetUser
with20
as theuserId
and{ isGuest: false }
, it could be expected that the email property would be dropped, which is not the case. However, other analytics libraries that have the same nomenclature (ga/firebaseset
methods for example) works the same way, so it is ok to keep using the same names, while also documenting this behaviour and indicating alternative methods to clear all the data. ForsetUser
we have theanonymize
method but forsetConsent
there is nothing available that clears all data, so it might make sense to add one as well.Describe alternatives you've considered
About the
loadIntegration
event type, there are some integrations that access it to get other data set in analytics. However, none of them is looking at theloadIntegration
event type specifically. They are either accessing thecontext
orconsent
variables, which probably means that theloadData
parameter is used not as an event but as a shortcut to get some analytics values, so we could ditch theevent
property altogether from theloadData
parameter as it is not an event per see.Regarding the changes for
analytics.user
,analytics.consent
andanalytics.integration
method names, maybe there is no need to have such verbose method names. Since we'll not change what data they return, it will continue to be clear for the developers what these methods are for, and we could simplify the naming a bit by just adding the prefixget{MethodName}
, to match the opposite methods we have that have the prefixset{MethodName}
for setting those values.Additional information
Decision log 19 Feb:
@onIntegrationInit
both for thetype
and forevent
(and export these constants for reusability);get{MethodName}
andset{MethodName}
. (addIntegration
will continue the same, but the getter will be changed togetIntegration
);