shimisnow / utm-manager

UTM Manager is a JavaScript library to extract and manipulate utm variables from a URL or string.

How to use

• Download the utm-manager-x.y.z.zip file from the latest release.
• Include the UTMManager libray in your project.

Using the library with tag <script>:

<script src="utm-manager.min.js" type="text/javascript"></script>

Using the library with RequireJS:

requirejs(['UTMManager'], (UTMManager) => {
  ...
})

After loading the library you can do something as:

const utm = new UTMManager('https://domain.net/?utm_source=google&utm_medium=cpc&utm_campaign=campaign-01')

utm.is('utm_source')
  .equals('google')
  .and()
  .is('utm_medium')
  .equals('cpc')
  .then(() => {
    console.log('Hey! This is a paid campaign from google!')
  })
  .otherwise(() => {
    console.log('This is not a paid campaign from google!')
  })

or

const utm = new UTMManager('https://domain.net/?utm_source=google&utm_medium=cpc&utm_campaign=campaign-01&utm_term=term-01')

let term = ''

// get utm_term if it exists and has value
utm.is('utm_term')
  .filled()
  .then(() => {
    term = utm.get( 'utm_term' )
  })

The given examples are the simple ones. Read the basic section and advanced section for more examples.

Documentation

UTMManager's documentation is included in the directory doc and each function can be viewed from the following links:

Manipulation functions

function	since
UTMManager()	1.0.0	Parses an URL or string and extract the utm variables
add()	1.1.0	Adds one or more variables
get()	1.0.0	Returns the value of one or more variables
remove()	1.0.0	Removes one or more variables
set()	1.0.0	Sets the value of one or more variables
toString()	1.0.0	Returns some or all variables grouped as a string

Condition functions

function	since
and()	1.0.0	Performs an and operation with the result of two verification with is()
defined()	1.0.0	Verifies if one or more variables are defined
equals()	1.0.0	Verifies if one or more variables are equals the given value
empty()	1.0.0	Verifies if one or more variables are empty
filled()	1.1.0	Verifies if one or more variables are defined and has value
not()	1.0.0	Verifies if all given variables are different from the given value
or()	1.0.0	Performs an or operation with the result of two verification with is()
undefined()	1.0.0	Verifies if one or more variables are undefined

Action functions

function	since
always()	1.0.0	Execute if the performed verification with is() return either true or false
otherwise()	1.0.0	Execute if the performed verification with is() return false
sort()	1.1.0	Sorts the variables
then()	1.0.0	Execute if the performed verification with is() return true

Util functions

function	since
result()	1.0.0	Return the boolean result from a condition function
sort()	1.1.0	Sorts the variables

How to build, lint and test

This tasks can be performed with Node.js or Docker containers. See the developer documentation for details.

Versioning

The release cycle is maintained under the Semantic Versioning guidelines.

Bugs and feature requests

Have a bug or a feature request? Please first search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.

Copyright and license

Code and documentation copyright 2020 the UTM Manager Authors. Code released under the MIT License.