Membership SDK#

Warning

Access to the membership SDK is restricted to specific Antavo partners. Please reach to Antavo via the service desk regarding any questions/issue about this topic

The Antavo Membership Site SDK provides a framework to help clients smoothly integrate with Antavo’s API system. The SDK includes all vital components necessary to develop a modern application. The Membership Site SDK significantly reduces development time as clients only need to develop application templates and stylesheets. The core components of the Membership Site SDK are written in php and the whole development cycle happens in a container environment therefore debugging might require entry-level knowledge of Docker and/or Docker-compose.

It is also strongly recommended that developers are familiar with :

Slim PHP - PHP micro framework
Redis - caching
Pug - Templating

The repository scheme is strongly linked to the Antavo API documentation and thus it is highly recommended that the developers fully understand the principles and processes of the Antavo APIs before starting.

Requirements#

Launching the Membership Site SDK requires the following components:

Quick-Start#

Development of the Membership Site SDK happens on a local computer so the code does not need to be submitted to the system before the testing phase. In order to initiate the development environment, all components listed in the ‘Requirements’ section need to be installed. The initiation process has the following steps:

Clone the original Microsite SDK Git repository to a local folder:
```
$ git clone https://your-repository-url.git
```
Navigate to the now downloaded folder. Add three mandatory environment variables in the docker-compose.yaml. These can be found on the api page in the settings of the Antavo Backoffice (https://loyalty.environment.antavo.com/brand_id/settings/general/api). Please contact your Antavo account manager if there are any problems accessing this data.
```
ANTAVO_ENVIRONMENT
ANTAVO_ACCESS_KEY
ANTAVO_SECRET_KEY
```
Launch docker-compose, which will build and run the microsite at http://localhost:3000.
```
$ docker-compose up --build --force-recreate
```
The development environment will run as a microservice in the background and will automatically detect changes in the templates and automatically refresh the locally displayed webpage.
A basic health check is available http://localhost:3000/hc

Updates#

Updates to Membership SDK by Antavo will require the docker image be updated using composer. This can be done using the docker environment

$ docker exec -it <brand_Membership SDK-backend>  /bin/sh
// Composer should be installed so this set is only needed if composer is not found
$ curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
$ composer install

Repository structure#

The Membership SDK is fully integrated into a gitlab repository, which fully automates the deployment of membership SDK. Standard git functionality and CVS functionality is fully available for multiple users.

Two branches are preconfigured for the repository: develop and master. These are connected to corresponding Antavo staging and production environments. Updates can be performed at anytime by pushing committed changes to the corresponding repository origin branch and the Antavo gitlab CI/CD configuration will automatically deploy to the corresponding environment. Configuration migration between staging and production can be easily performed by an authorized user, using standard git methods e.g., merging and/or cherrypicking.

Project structure#

The finalized project structure is:

├── Dockerfile-php
├── README.md
├── composer.json
├── composer.lock
├── docker-compose.yml
├── etc
│   ├── nginx
│   │   ├── antavo
│   │   │   ├── extras.conf
│   │   │   ├── fastcgi_params
│   │   │   └── options.conf
│   │   ├── microsite.conf
│   │   └── nginx.conf
│   └── php
│       ├── etc
│       │   ├── browscap.ini
│       │   ├── php
│       │   │   └── conf.d
│       │   │       ├── assertion.ini
│       │   │       ├── browscap.ini
│       │   │       ├── global.ini
│       │   │       ├── memcached.ini
│       │   │       ├── newrelic.ini
│       │   │       ├── opcache.ini
│       │   │       ├── phpmail.ini
│       │   │       └── session.ini
│       │   └── php-fpm.d
│       │       └── www.conf
│       └── ssmtp
│           ├── revaliases
│           └── ssmtp.conf
├── public
│   ├── index.php
│   └── static
│       └── js
│           └── script.js
├── src
│   ├── Controllers
│   │   └── RewardController.php
|   ├── locales
│   |   ├── de.json
│   |   └── en.json
│   ├── styles
│   │   ├── colors.scss
│   │   ├── default.scss
│   │   ├── globals
│   │   │   └── button.scss
│   │   └── pages
│   │       └── default.scss
│   └── templates
│       ├── activities.pug
│       ├── error
│       │   ├── 404.pug
│       ├── faq.pug
│       ├── history.pug
│       ├── index.pug
│       ├── layouts
│       │   ├── default.pug
│       │   └── login.pug
│       ├── login.pug
│       ├── partials
│       │   ├── header.pug
│       │   └── notice.pug
│       ├── profile.pug
│       ├── profiling.pug
│       ├── registration.pug
│       ├── rewards
│       │   └── reward.pug
│       └── rewards.pug
└── vendor

where

/src/locales:

The root directory for the localization library.

/public/static:

All files included in this folder are available through the _static url. For example, image.png can be reached the following way.

/_static/image.png

/src/styles:

All files included in this folder are available through the _styles url. For example, main.scss can be reached by

/_styles/main.css

Sass scss files are automatically compiled into CSS in the development environment and are cached in the production environment.

/src/templates:

Location of template files

Demo Project#

A demo project, a fully functional Membership Site has been created which can be used as a development basis/inspiration for the creation of your own project. The source code for the demo project can be found here

Authentication#

Any request that is not authorized will be forwarded to the /unauthorized endpoint. A customer is authenticated if there is a __alc cookie which contains a valid, signed token or if the customer stored in session, using REDIS. Authentication is possible via the Antavo Javascript SDK or from the Loyalty Platform via a login. The presence of a __alc cookie will result in a login of that specific customer, regardless of session data.

Configuration#

The Membership Site SDK was built with elements, each configurable through its own repository.

Environment variables:: The inner workings of the program can be adjusted using environmental variables. The currently supported environmental variables are located in the source code of the demo project’s docker-compose.yml file

Layout definition#

A new project requires the creation of a layout definition which serves as a frame for the upcoming page. The layout should feature common elements which appear across all pages e.g., the content of the header, the sidebar. There is an option to define multiple layers, which can be dynamically activated, even on a per-page basis. A layout can be defined in the following steps:

Navigate to the project’s root directory
1. Enter the /src/templates/layouts folder.
  1. create this folder if it does not exist
Create a new file called default.pug.
1. The file extension depends on the template engine used for rendering.
Establish the framework within the file. Use:
1. emphasis HTML tags
2. head and body tags.
Stylesheets and scripts can be inserted here later.
Create a new content block named ‘content’ within the body tag.
1. This will be the place for the upcoming loyalty page.

Creating a new page#

The Membership Site SDK features a standard algorithm for page creation, which allows the expansion of your system with various pages, using a dynamic routing capture mechanism. These are the following steps to create an new FAQ page:

Navigate to the src/templates folder
Create a new file, called faq.pug.
The file extension may depend on the template engine used for rendering.
Create a content block ensuring that the name matches the name of the block specified in the layout
Add content.
The finished page is instantly available at http://localhost:3000/faq

Standard (non-custom) routing uses the page name as a slug

http://localhost:3000/{pageName}

Non-standard routing is possible through controller definitions. These enable custom code for data processing before page rendering and dynamic URLS.

An example using Reward can be found here. This controller will need to be registered here.

HTTP Error handling#

Custom templates can be defined for each HTTP error code and must be stored in the /src/templates/error folder. A custom 404 page is mandatory and additional error pages must follow the {error_code}.pug naming convention.

Localization#

The Membership Site SDK uses a pre-built library to generate localizations. Translations files are simple php arrays with the key and the corresponding translations. Placeholders can also be used in the translation keys and localization files should be stored at src/locales`

└── src
    ├── locales
    │   ├── de.php

The following de.json translation file:

return [
 "Show more" => "Zeig mehr"
];

will result in the corresponding translation in views for the de locale:

__("Show more'') // will print "Zeig mehr"

The locale of the currently logged in customer can be changed with the ?locale=<international language code> query string parameter. The value of the parameter must match the name of the localization file.

Note

The session’s locale remains active until the next logout, session cancellation or a locale overwrite.

Resources and repositories#

Reference to internal pages can be made by directly referring to the location of the template page within the src directory structure. For example, a link to the history.pug, located in the root directory (src folder) can be made with the following code

li(class='')
     a(href='/history') History

Querying/modifying entities in the pre-defined template can be done through Membership Site SDK’s built-in mechanism. The template always contains a global variable api which user can use to access multiple repositories, Currently the following repositories can be accessed through the API object listed with available methods:

Activities
- activitiesService.getAll(params)
Claimed Reward
- claimedRewardService.getAll(params)
Coupons
- couponService.getAll(params)
Customer
- customerService.getCurrentCustomer(params)
- customerService.hasCurrentCustomer(params)
- customerService.setCurrentCustomer(params)
- customerService.refreshCurrentCustomer(params)
FAQ
- faqService.getAll(params)
History
- historyService.getAll(params)
Profiling
- profilingService.getAll(params)
- profilingService.getOne(profileId, params)
Reward Category
- rewardService.getAll(params)
Rewards
- rewardService.getAll(params)
- rewardService.getOne(rewardId, params)

For example, the rewards in the template can be done the following way:

-var rewards = rewardService.getAll(params)

The services also are enabled to add custom GET parameters to any request:

-var rewards = rewardService.getAll({'fields': 'instructions'})

To query an individual reward:

-var reward = rewardService.getOne("reward_id")

Customer fields can be accessed using the following form.

-var customer = customerService.getCurrentCustomer().spendable

POST route#

The Membership Site SDK defines a universal POST route and thus all POST requests to the Microsite will arrive at the Antavo API. The following example demonstrates this process by assigning a reward, with an ID reward123 to a customer

A POST request must be sent to this endpoint:

/customers/customerid/rewards/reward123/claim

A new form is defined in the template: The method has to be POST, while the action is:
```
/customers/__customerId__/rewards/reward123/claim
```
The current customer ID can be automatically included by using the __customerId__ placeholder in the URL.
The input fields are defined in the form, inputting the endpoint’s ingoing parameters. These will be automatically sent with the API request.
The API query will happen with the form submission and by default the browser will be redirected to the page where the request originates. This can be overwritten with the __redirectUri input parameter, which should be in the form as a hidden input.
The API response can be requested through the api object the following way:
```
getLastApiResponse
```

This method will provide the last API response but can only be requested once, after which it will be deleted. The response should be stored for the context of the view.

Creating stylesheets#

Stylesheets can be written in SCSS format and the Membership Site SDK automatically processes, serves and cache all finished SCSS files. The compiled version of the stylesheets stored in the src/styles folder can be reached at http://localhost:3000/_styles/scssFileName.css

A new stylesheet can be created the following way:

Navigate to the :file:’/src/styles` folder
Create a new file, called test.scss.
The compiled CSS is made available on the following link: http://localhost:3000/_styles/test.css #. This can be reference internal as /_styles/test.css

This css can already be integrated into the layout:

<link rel="stylesheet" href="http://localhost:3000/_styles/test.css">

Any changes to the stylesheet requires a restart of the container.