Adobe plug-in: apl (appendToList)
The apl
plug-in allows you to safely add new values to list-delimited variables, such as events
, linkTrackVars
, list
, and others.
- If the value you want to add doesn’t exist in the variable, then the code adds the value to the end of the string.
- If the value you want to add already exists in the variable, then this plug-in does not change the value. This features allows your implementation to avoid duplicate values.
- If the variable you want to add to is empty, then the plug-in sets the variable to the new value.
Adobe recommends using this plug-in if you want to add new values to existing variables that contain a string of delimited values. This plug-in is not necessary if you prefer to concatenate strings for variables containing delimited values.
Install the plug-in using the Web SDK or Web SDK extension
This plug-in is not yet supported for use within the Web SDK.
Install the plug-in using the Adobe Analytics extension
Adobe offers an extension that allows you to use most commonly-used plug-ins with Adobe Analytics.
-
Log in to Adobe Experience Platform Data Collection using your AdobeID credentials.
-
Click the desired tag property.
-
Go to the Extensions tab, then click on the Catalog button
-
Install and publish the Common Analytics Plugins extension
-
If you haven’t already, create a rule labeled “Initialize Plug-ins” with the following configuration:
- Condition: None
- Event: Core – Library Loaded (Page Top)
-
Add an action to the above rule with the following configuration:
- Extension: Common Analytics Plugins
- Action Type: Initialize APL (Append To List)
-
Save and publish the changes to the rule.
Install the plug-in using custom code editor
If you do not want to use the Common Analytics Plugins plug-in extension, you can use the custom code editor.
- Log in to Adobe Experience Platform Data Collection using your AdobeID credentials.
- Click on the desired property.
- Go to the Extensions tab, then click the Configure button under the Adobe Analytics extension.
- Expand the Configure tracking using custom code accordion, which reveals the Open Editor button.
- Open the custom code editor and paste the plug-in code provided below into the edit window.
- Save and publish the changes to the Analytics extension.
Install the plug-in using AppMeasurement
Copy and paste the following code anywhere in the AppMeasurement file after the Analytics tracking object is instantiated (using s_gi
). Preserving comments and version numbers of the code in your implementation helps Adobe with troubleshooting any potential issues.
/******************************************* BEGIN CODE TO DEPLOY *******************************************/
/* Adobe Consulting Plugin: apl (appendToList) v4.0 */
function apl(lv,va,d1,d2,cc){var b=lv,d=va,e=d1,c=d2,g=cc;if("-v"===b)return{plugin:"apl",version:"4.0"};var h=function(){if("undefined"!==typeof window.s_c_il)for(var k=0,b;k<window.s_c_il.length;k++)if(b=window.s_c_il[k],b._c&&"s_c"===b._c)return b}();"undefined"!==typeof h&&(h.contextData.apl="4.0");window.inList=window.inList||function(b,d,c,e){if("string"!==typeof d)return!1;if("string"===typeof b)b=b.split(c||",");else if("object"!==typeof b)return!1;c=0;for(a=b.length;c<a;c++)if(1==e&&d===b[c]||d.toLowerCase()===b[c].toLowerCase())return!0;return!1};if(!b||"string"===typeof b){if("string"!==typeof d||""===d)return b;e=e||",";c=c||e;1==c&&(c=e,g||(g=1));2==c&&1!=g&&(c=e);d=d.split(",");h=d.length;for(var f=0;f<h;f++)window.inList(b,d[f],e,g)||(b=b?b+c+d[f]:d[f])}return b};
/******************************************** END CODE TO DEPLOY ********************************************/
Use the plug-in
The apl
function uses the following arguments:
lv
(required, string): The variable that contains a delimited list of items to add a new value tovta
(required, string): A comma delimited list of the new value(s) to add to thelv
argument’s value.d1
(optional, string): The delimiter used to separate the individual values already contained in thelv
argument. Defaults to a comma (,
) when not set.d2
(optional, string): The output delimiter. Defaults to the same value asd1
when not set.cc
(optional, boolean): A flag that indicates if a case-sensitive check is used. Iftrue
, the duplication check is case-sensitive. Iffalse
or not set, the duplication check is not case-sensitive. Defaults tofalse
.
The apl
function returns the value of the lv
argument plus any non-duplicate values in the vta
argument.
Examples
// Set the events variable to "event22,event24,event23".
s.events = "event22,event24";
s.events = apl(s.events,"event23");
// The events variable remains unchanged because the apl function does not add duplicate values
s.events = "event22,event23";
s.events = apl(s.events,"event23");
// Set the events variable to "event23" if the events variable is blank
s.events = "";
s.events = apl(s.events,"event23");
// Append a value to eVar5. The value of prop4 remains unchanged.
// The value of eVar5 is "hello|people|today".
s.prop4 = "hello|people";
s.eVar5 = apl(s.prop4, "today", "|");
// Sets prop4 to "hello|people,today". Be mindful of correct delimiters!
s.prop4 = "hello|people";
s.prop4 = apl(s.prop4, "today");
// Sets the events variable to "event22,event23,EVentT23". Be mindful of capitalization when using the cc argument!
s.events = "event22,event23";
s.events = apl(s.events,"EVenT23", ",", ",", true);
// Sets the events variable to "event22,event23,event24,event25".
s.events = "event22,event23";
s.events = apl(s.events, "event23,event24,event25");
// Sets linkTrackVars to "events,eVar1,campaign".
// The last three arguments at the end of this apl call are not necessary because they match the default argument values.
s.linkTrackVars = "events,eVar1";
s.linkTrackVars = apl(s.linkTrackVars, "campaign", ",", ",", false);
// This apl call does not do anything because the code does not assign the returned value to a variable.
s.events = "event22,event24";
apl(s.events, "event23");
// Sets the list2 variable to "apple-APPLE-Apple".
// Since the two delimiter arguments are different, the value passed in is delimited by "|", then joined together by "-".
s.list2 = "apple|APPLE";
s.list2 = apl(s.list2, "Apple", "|", "-", true);
// Sets the list3 variable to "value1,value1,value1" (unchanged).
// Only new values are deduplicated. Existing duplicate values remain.
s.list3 = "value1,value1,value1";
s.list3 = apl(s.list3,"value1");
Version History
4.0 (March 19, 2021)
- Added version number as context data.
3.2 (September 25, 2019)
- Fixed compatibility issues with
apl
calls that used older versions of the plug-in - Removed console warnings to reduce size
- Added
inList 2.1
3.1 (April 22, 2018)
d2
argument now defaults to the value of thed1
argument when not set
3.0 (April 16, 2018)
- Complete reanalysis/rewrite of plug-in
- Added advanced error checking
- The
vta
argument now accepts multiple values at one time - Added the
d2
argument to format the return value - Changed the
cc
argument to a boolean
2.5 (February 18, 2016)
- Now uses the
inList
function for comparison processing
2.0 (January 26, 2016)
d
(Delimiter) argument now optional (defaults to a comma)u
(Case-sensitivity flag) argument now optional (defaults to case-insensitive)- Regardless of the
u
(Case-sensitivity flag) argument, the plug-in no longer appends a value to a list if the value already exists in the list