Skip to main content
Log inGet free account
Last Reviewed: March 23, 2021

Drupal SDK

Install, configure, and use Edge Integrations with Drupal.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

The Edge Integrations personalization system for Drupal consists of two main parts:

  • Pantheon Edge Integrations library - a CMS-agnostic PHP library that allows reading, process, and set vary headers to be recognized by Pantheon Advanced Global CDN.

  • A collection of Drupal modules in the Edge Integrations Drupal SDK ecosystem that provide Smart Personalization blocks and preview functionality. If you decide to forgo using the SDK, installing the Smart Content CDN module will give you everything you need to get up and running with personalization.

Before You Begin

Note

Before you can use Pantheon Edge Integrations, you must be connected to Pantheon’s Advanced Global CDN, and your site's vary headers and custom VCL rules must have been provisioned by Professional Services. Contact your Account Manager if you have questions about how to add and configure this for your site.

  1. Ensure you have a working Drupal 8+ installation ready.

  2. Install the necessary modules and dependencies, which can be pulled with Composer. As noted above, this can be achieved either by using the Edge Integrations Drupal SDK, or the Smart Content CDN module.

    Edge Integrations Drupal SDK

    Installing the Edge Integrations Drupal SDK will give you all the documentation in the Drupal SDK package as well as the Edge Integrations Global Library, which is required for Edge Integrations to work optimally in Drupal. You should choose this option if you do not plan on using Smart Content in your Drupal site. If you plan on using Smart Content to manage personalized content, you need to install both the Drupal SDK package as well as smart_content_cdn.

    composer require pantheon-systems/edge-integrations-drupal-sdk

    Smart Content CDN Module

    Installing the Smart Content CDN module will install the Smart Content module and the Edge Integrations Global Library. This option does not include documentation in the Drupal SDK package. You should choose this option if you plan on using the Smart Content ecosystem to manage personalized content in your Drupal site. If you installed smart_content_cdn with Composer, you do not need to install the Edge Integrations Drupal SDK.

    composer require pantheon-systems/smart_content_cdn

  3. The Smart Content Preview module is an optional package you can use to preview your personalized content. It allows you to preview content personalized with Smart Content and Smart Content CDN. It can also be installed with Composer:

    composer require drupal/smart_content_preview

Configure Smart Content CDN

  1. Enable the Smart Content module.

  2. Enable the Smart Content CDN and Smart Content Block modules.

  3. Enable the Smart Content Preview module.

  4. Navigate to the Configuration > System > Smart Content CDN Configuration page at /admin/config/system/smart-content-cdn.

  5. Enable the Vary Header toggle.

  6. Set default Geo value to a 2-letter country code in all uppercase (e.g. US). This should match the default segment in Step 8 of the Geolocation section.

  7. Save the configuration.

Smart Content CDN Usage

There are a few different ways to use Smart Content CDN. In this doc, we will cover targeting via Geolocation, and Interest via Taxonomy.

Configure Geolocation Segments

  1. Navigate to /admin/structure/smart_content_segment_set.

  2. Click +Add Global Segment Set. Segment Set entities

  3. Provide a label (e.g. Geo).

  4. Click Add Segment. Add Segment

  5. Change the segment name to something meaningful (e.g. Canada, US, etc).

  6. Select Geo condition under the Smart CDN category. Select Geo

  7. Click Add Condition.

  8. Fill in value for Equals. Fastly is currently set up to return 2-letter country codes for geolocation. If your country is USA, type in “US” in all uppercase letters.

    Segment Equals

  9. Add all of the required segments and select one that will act as the default.

  10. Make sure that Preview checkboxes are unchecked.

  11. Click Save.

  12. Navigate to Structure > Block layout > Add custom block at /block/add.

  13. Add content blocks for each segment. For instance "Hello Canada!", "Hello US!", etc.

  14. Navigate to the Block Layout section of the site at /admin/structure/block.

  15. Click Place block in the region you want the geo-block to appear, and search for SSR Decision Block.

  16. Configure the Decision Block: select your new Geolocation Segment set; click Select Segment Set.

  17. In the Configure Reactions section, click Edit, and add the “Hello…” blocks you created to the corresponding segment.

  18. Add placement configuration to the block and save the block.

  19. Navigate to the page with the block and you will see the personalization you configured.

  20. If you don’t have a VPN client, navigate to the Segments Sets Admin page at /admin/structure/smart_content_segment_set, edit the set, select one preview checkbox, and save.

    Smart Content Preview

The content corresponding to this segment will display. Please note that only users who are logged in can access the content in preview; anonymous users will not have access.

Configure Interest via Taxonomy

In this section, we identify the content type where you want to use personalization by Interest, add a taxonomy field, and connect it to the pertinent vocabulary. For this example, we will assume it is Tags field_tags.

  1. Navigate to Admin > Config > System > Smart Content CDN at /admin/config/system/smart-content-cdn. In the configuration form for Smart CDN, select the checkbox for Tags. The form automatically reads all available taxonomy reference terms for all content types and allows you to select them. Interest Fields

  2. Create tags for your Tags vocabulary.

  3. Review your content and tag it using the Tags vocabulary (e.g. "Biking").

  4. Navigate to /admin/structure/smart_content_segment_set to configure interest/taxonomy segments.

  5. Click +Add Global Segment Set. Add Global Segment Set

  6. Provide a label (e.g. Interest) - the name isn't critical.

  7. Click Add Segment. Add Segment

  8. Change segment name to something meaningful. We recommend matching the term name (e.g. "Biking").

  9. Select Interest condition under the Smart CDN category.

  10. Click Add Condition.

  11. Fill in value for Equals with the taxonomy term name. Interests

  12. Set default segment and save.

  13. Create content blocks per segment; they can also be views or block types.

  14. Add another SSR Decision Block, select Interest segment, and configure reactions. Place block and save.

  15. Navigate to the page with the block and you will see the personalization you configured.

  16. If you don’t have a VPN client, navigate to the Segments Sets Admin page at /admin/structure/smart_content_segment_set, edit the set, select one preview checkbox, and save.

The content corresponding to this segment will display. Please note that only users who are logged in can access the content in preview; anonymous users will not have access.

Additional Configuration

There is some additional configuration that you can apply to Smart Content. The Interest is of particular importance. It is calculated by the frequency with which the page tagged with a certain term is visited.

To set up the threshold after which the user will be placed in the particular Interest segment:

  1. Navigate to the Configuration > System > Smart Content CDN Configuration page at /admin/config/system/smart-content-cdn. configform

  2. Update the Interest threshold value.

  3. Clear the cache.

Recap

The Smart Content CDN module extends Smart Content's functionality, and leverages the Pantheon Edge Integrations, a CMS-agnostic PHP library. The setup steps above provide two use cases: Geolocation and Interest, but there is much more you can accomplish with Smart Content and content personalization. For more information about the module, and other possible use cases, refer to the Smart Content CDN module.

More Information

Pantheon Edge Integrations uses header data to provide a personalization object that is utilized for personalizing content for each user. To make use of the PHP library, ensure PHP can use the class:

use Pantheon\EI\HeaderData;

Class Methods

In order to use the class methods, you need to create a HeaderData object:

  • $headerData = new HeaderData();
$headerData->getHeader(key)

Use header key to return raw header data.

Examples:

  • key: “Audience” => return: “geo:US”

  • key: “Interest” => return: “27”

$headerData->parseHeader(key)

Use header key to return parsed header data array.

Examples:

  • key: “Audience” => return: “geo:US”

  • key: “Interest” => return: “27”

$headerData->returnPersonalizationObject()

Return an array with personalization data.

Examples:

  • key: “Audience” => return: “geo:US”

  • key: “Interest” => return: “27”

Global Methods

There are global methods that mirror the class methods in order to ease the API usage. These include:

  • HeaderData::personalizationObject()

  • HeaderData::parse()

  • HeaderData::header()

  • HeaderData::returnVaryHeader()

For more information on what these methods expect and return, refer to Pantheon's API documentation.

Obtain Header Within a Custom Module

The follow can be used in any class context, or procedural context in any hook.

To include the library, run:

use Pantheon\EI\HeaderData;

Use the following snippet to obtain the header data object:

    #Get header data.
    $smart_content_cdn = new HeaderData();
    $p_obj = $smart_content_cdn->returnPersonalizationObject();

Known Issues

There is a known conflict with the Internal Page Cache module. This module does not provide any benefit when used in a Pantheon environment, but may be recommended (or enabled) for some modules. Our recommendation is to disable the Internal Page Cache module to ensure compatibility with Edge Integrations. Dynamic Page Cache is compatible with Edge Integrations and does not have the same restrictions.