Data privacy API

This page describes the API for handling personal data protection tasks if you are developing a custom module in Java. The API is applicable also for the purposes of GDPR – General Data Protection Regulation (Regulation (EU) 2016/679). The API covers two areas of personal data protection: handling visitor consent and managing cookies.

To use the visitor API, make sure that your project depends on the Visitor manager module:

The VisitorManager and the Visitor are the central interfaces needed for handling visitor information. The magnolia-privacy-visitor-manager module provides a JCR-based implementation for the Visitor manager (JcrBasedVisitorManager), which stores data in the JCR visitors workspace.

Getting VisitorManager

The VisitorManager is a singleton. To get an instance, inject it in the public constructor of the class where you want to use it.

package info.magnolia.documentation.gdpr;

import info.magnolia.consent.visitor.VisitorManager;
import javax.inject.Inject;

public class MyClass {
    private final VisitorManager visitorManager;

    @Inject
    public MyClass(VisitorManager visitorManager){
        this.visitorManager = visitorManager;
    }
}

Line 11: Assigns the injected VisitorManager to the private final class member variable.

Getting a visitor

Use the Visitor to get a visitor.

Visitor visitor = visitorManager.getVisitor("visitor@example.com");
Consent consent = visitor.getConsent();

Getting all references to a visitor

Set<PrivateRecordReference> references = visitorManager.getReferences(visitorManager.getVisitorIdForRequest());

Deleting all visitor data

// delete the visitor data by a given visitor id; done in two steps for security reasons

// request deletionId
String deletionId = visitorManager.requestVisitorDeletion("visitor@example.com");

// delete the visitor by deletionId
visitorManager.confirmDeletion(deletionId);
Deleting visitor data is done usually upon a request coming from a consent confirmation link (sent via email).

The source can be a URL, an email address or a phone number where the last consent update came from.

String source = consent.getSource();

Consent status may be given, denied or withdrawn.

Consent.ConsentStatus consentStatus = consent.getFields().get("email");

The following example changes the previous consent status to given with an expiration of one month:

Calendar expire = Calendar.getInstance();
expire.add(Calendar.MONTH, 1);

ConfiguredConsent.builder()
                    .source("mailto:visitor@example.com")
                    .field("email", Consent.ConsentStatus.given)
                    .expire(expire)
                    .build();

Managing cookies

To use the Cookie manager API make sure that your project depends on the Cookie manager module:

To handle cookies on the server side, Magnolia provides CookieManager. The Cookie manager knows about a website visitor’s consent that is related to cookies.

Instead of utilizing the java core cookie API, we recommend using the Cookie manager since the manager only adds cookies upon consent given by a website visitor.

Getting CookieManager

The Cookie manager implementation is a singleton. To get an instance, inject it in the public constructor of the class where you want to use it.

import info.magnolia.consent.cookie.CookieManager;

public class CookieBox {
    private final CookieManager cookieManager;

    public CookieBox(CookieManager cookieManager) {
        this.cookieManager = cookieManager;
    }

    public void doSomething {
        // use the cookieManager according do your needs
    }
}

Line 7: Assign the injected cookieManager to private final class member variable.

The method returns a Cookie wrapped in an Optional from the current request by a given cookie name.

Signature

Optional<Cookie> getCookieFromRequest(CookieDefinition cookieDefinition);

Example

public Cookie getCookie(String cookieId){
    if(cookieManager.getCookieDefinition(cookieId).isPresent()){
        return cookieManager.getCookieFromRequest(cookieManager.getCookieDefinition(cookieId).get()).orElse(null);
    }
    return null;
}

The method returns the cookie object or null by a given cookie id.

Adding a cookie with the Cookie manager requires a CookieDefinition. You can get a cookie definition as defined in the Cookies app with the Cookie manager, see getting and adapting a cookie definition.

The cookie is only added if the website visitor has given consent for the cookie.

Signature

void addCookie(CookieDefinition cookieDefinition)

Example

public void setMonsterCookie(String value) {
    if (cookieManager.getCookieDefinition(MONSETRCOOKIE_ID).isPresent()) {
        CookieDefinition cookieDefinition = cookieManager.getCookieDefinition(MONSETRCOOKIE_ID).get();
        cookieDefinition.setValue(value);
        cookieManager.addCookie(cookieDefinition);
    }
}

Line 4: You can override properties of the definition coming from the Cookies app.

The method checks whether the website visitor has given consent for a potential cookie. You need a CookieDefinition to check for consent. Also, read Understanding the decision whether a cookie is set or not, which explains the check consent mechanism for a specific cookie.

Signature

boolean isCookieConsented(CookieDefinition cookieDefinition)

Example

public boolean monsterCookieConsented() {
    return cookieManager.getCookieDefinition(MONSETRCOOKIE_NAME).isPresent() &&
           cookieManager.isCookieConsented(cookieManager.getCookieDefinition(MONSETRCOOKIE_NAME).get());
}

The method returns a CookieDefinition by a given cookie id.

You need CookieDefinition instances as arguments for the #addCookie and #isCookieConsented methods of the Cookie manager.

Returned cookie definitions are those managed with the Cookies app. The Cookie manager always returns a clone of the definition as configured in the Cookies app. This means that you also can override properties of the cookie definition as set in the Cookies app.

Signature

Optional<CookieDefinition> getCookieDefinition(String cookieId)

Example

public CookieDefinition getMonsterCookieDefinition(){
    return cookieManager.getCookieDefinition("monsterCookie").orElse(null);
}
Feedback