Page tree
Skip to end of metadata
Go to start of metadata

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.

Handling visitor and consent information

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

<dependency>
  <groupId>info.magnolia.privacy</groupId>
  <artifactId>magnolia-privacy-visitor-manager</artifactId>
</dependency>

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");

Getting visitor consent

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);

Note: Deleting visitor data is done usually upon a request coming from a consent confirmation link (sent via email). 

Getting consent source

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

String source = consent.getSource();

Checking consent status

Consent status may be given, denied or withdrawn.

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

Updating consent

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();

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

<dependency>
  <groupId>info.magnolia.privacy</groupId>
  <artifactId>magnolia-privacy-cookie-manager</artifactId>
</dependency>


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.

 Click to see the complete CookieManager interface

package info.magnolia.consent.cookie;
 
import info.magnolia.consent.cookie.definition.CookieDefinition;
 
import java.util.Optional;
 
import javax.servlet.http.Cookie;
 
/**
 * Manager for cookies.
 */
public interface CookieManager {
 
    /**
     * If the cookie represented by given {@link info.magnolia.consent.cookie.definition.CookieDefinition} can be send to client.
     */
    boolean isCookieConsented(CookieDefinition cookieDefinition);
 
    /**
     * Gets a cookie definition configured under /modules/cookie-manager/config/cookies/.
     */
    Optional<CookieDefinition> getCookieDefinition(String cookieName);
 
    /**
     * Adds cookie created from given {@link info.magnolia.consent.cookie.definition.CookieDefinition} to the current request if consent for this cookie was given.
     */
    void addCookie(CookieDefinition cookieDefinition);
 
    /**
     * Gets a cookie from current request.
     */
    Optional<Cookie> getCookieFromRequest(CookieDefinition cookieDefinition);

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

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.

(info) 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.

Checking consent for a cookie

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);
}