Communication Preferences

Skip to end of metadata
Go to start of metadata

Overview

Manage and track your various communication channels (subscriptions), and provide customers with the ability to review and control their communication preferences. Create subscription data points in your schema, retrieve users who have opted in and send out notifications, newsletters and other forms of communication using an IdentitySync ETL job, and offer users a one-click unsubscribe. 

Communication preferences (the Subscriptions Object) are stored in Email Accounts.

Communication preferences features include the following: 

  • An out-of-the-box subscription widget that can be highly customized using Gigya’s UI Builder. The widget displays to end-users their subscription status. 
  • Clear opt-in and opt-out flows for complying with privacy regulations, including double opt-in confirmation. 
  • Capture and track communication consent using the Consent Vault. If your subscription requires double opt-in, consent is captured only after users opt-in to the subscription. 
  • Full support for exporting and importing subscriber data to third-party platforms, such as Email Service Providers (ESPs), either with IdentitySync (Gigya’s ETL service) or using accounts.search.

Double Opt-in

This parameter or feature is part of our Early Adopters Program. To find out if you are eligible for participation, contact your Account Manager by filling out a support form. You can access the support page by clicking Support on the upper menu after logging into your Gigya Console

You can set communication channels to require double opt-in, i.e., to require that users confirm via email that they do, indeed, wish to subscribe. This confirmation may be required by law in certain countries. The process of configuring a double opt-in requirement for a subscription is as follows: 

  1. Define the subscription as requiring double opt-in, either in the schema editor, or the UI Builder (see below). 
  2. (Optional) Configure the URL of the page to which subscribers are redirected after confirmation, and the expiration time of the confirmation link, in the Policies page of Gigya's Console.  Otherwise, Gigya defaults will be used.For more information, see Policies: Double Opt-In
  3. (Optional) Set up an email template for the confirmation email that will be sent out to subscribers. Otherwise, the Gigya default template will be used. For more information, see Email Templates

While Gigya offers a full suite of solutions designed to help clients comply with applicable data privacy laws, it is the clients' responsibility to comply with its obligations under such data privacy laws. Please consult with your legal team regarding such data privacy laws prior to implementation of the Gigya suite of solutions.

 

Implementation

Create and Map a Subscription 

When you create a new subscription (communication channel), you add a new Subscriptions Object to the schema. 

Create Subscription Using the Schema Editor

  1. Open the Schema Editor in Gigya's Console.
  2. Click Create Field.
  3. In the Accounts database, select the Subscriptions type. Give the field a name and click Create
  4. In the Properties pane on the right hand side, you can flag this subscription as Require Double Opt-In. This means that users who wish to subscribe, will need to confirm their subscription via email (see below). For more information on working with the schema editor, see Schema Editor

Create and Map a Subscription Using the UI Builder

You can create the subscription in the UI Builder, or use the UI Builder to add a subscription checkbox to a screen, and map it to a subscription that already exists in the schema. Usually, you should add the subscription both to the screens on which users subscribe (e.g. a full or lite registration screen), and to the profile update screen, where registered users manage their subscriptions.

To do so: 

  1. Open the Screen-Sets page in Gigya's Console, and open the relevant screen for editing in the UI Builder (e.g. a registration screen). 
  2. If there is an existing subscription checkbox in the screen that is mapped to the data.subscriptions field, you should delete it. 
  3. In the layout editor, on the left hand side scroll to the Widgets section, and from there, drag the Subscription widget to the canvas. 

  4. With the subscription widget selected, open the Mapped Field control on the left. If the subscription already exists in the schema, select it (make sure you click on the email field under the subscription). If you wish to create a new subscription, under the Subscriptions node, click Add. Give the new subscription an ID and a description and click Add. When your subscriptions require double opt-in, this description will be added to the confirmation email sent to subscribers. 
  5. You can revise the Label as needed (e.g., from "Subscribe to our newsletter", to "Subscribe to updates about unusual weather". 
  6. In the Schema section, under Require Double Opt-In, select whether the subscription requires double opt-in. This means that users who wish to subscribe, will need to confirm their subscription via email (see below).The default is "Not Required". 
  7. In the same section, you can change the description as needed. 
  8. Save your changes. 
  9. Repeat the process for the relevant ProfileUpdate screen, making sure you include a subscription widget for all active subscriptions and map the widget accordingly. This way, when a registered user opens their "Edit Profile" screens, they will see which subscriptions they subscribed to, and the double opt-in status of those subscriptions. 

One of the main advantages of using the Subscription widget rather than mapping any UI element to the subscription field, is that in an 'Update Profile' screen, it will display the double opt-in status (Not Confirmed, Pending, or Confirmed).

Tags

You can add custom tags to the Subscriptions object. Add tags as follows: 

  1. Drag a Metadata control to the screen. 
  2. Map the control to the tags field of the relevant subscription. 
  3. Under Value format, select "JavaScript expression". 
  4. In the Value field, add the tags as needed. For example, add an array of tags according to the following example:

    ["hasCats","hasDogs","hasFish"]
  5. Save changes. 

In the UI Builder you may also save the tags as Value format string of the Metadata control, however, you must be sure to not include any quotes around the individual tags, or your tags will be saved with the quotes as part of the tag name, i.e.,

Saving as a string: "hasCats", "hasDogs",  "hasFish"
 
results in: 
"tags": [
      "\"hasCats\"",
      " \"hasDogs\"",
      " \"hasFish\""
]

Additionally, note that tags are not appendable, whenever you set tags to a user, the previous tag(s) are replaced with the new tag(s).

Adding tags does not replace the need to map the subscription itself, using the subscription widget.

 

User-Facing Subscription Management

Enable One-Click Unsubscribe

You have the option of automatically updating Gigya's database when the user chooses to unsubscribe from your service (for example, when clicking an "unsubscribe" link in an email sent by an ESP). After the user submits the "unsubscribe", send a request to Gigya using the accounts.unsubscribe method, which changes that user's subscription status ("isSubscribed=false").

 

Communication Preferences Screen

You can create a communication preferences screen, that displays to users their communication preferences, and allows them to opt in, opt out, and control other paremeters, such as the communication frequency.

If you are using Gigya's Screen-Sets, users should be able to manage their subscriptions through the Communication screen that is part of the Profile Update screen-set. Make sure you enable this by adding the subscription widget to that screen (add one widget for each subscription), and map it to the relevant subscriptions, as explained above. 

After the subscription widget is added to the screen, users can see their double opt-in status (for subscriptions that require double opt-in), and choose to subscribe or unsubscribe by checking or unchecking the subscription box. 




Identity Access with Email Accounts

Communication preferences (the Subscriptions Object) are stored in Email Accounts. When either Lite Registration or Subscriptions are enabled for your Gigya account, your Identity Access page changes and now includes a toggle between a UID-based and an Email-based view: 

  • The UID based view shows only fully-registered users, i.e., those users for whom a UID exists. When using this view, the Identity Access guide applies fully. 
  • The Email based view shows email accounts, for whom either a full account, or a lite registration, or both, exist. When comparing this to the UID-based view: 
    • The Status column displays whether users are registered (R) or Lite (L), or both. 
    • The email account does not include Identities (i.e. social and/or site identities). 
    • The email-based view unifies all profile, custom and subscription data for a primary email address. 
    • The email-based view may be updated from Lite Registration screens as well as from changes made to the full account. 


Querying Subscription Data

You can use the Identity Query Tool or accounts.search to retrieve subscription data. Note that subscription data is available from accounts.search only when querying from 'emailAccounts'. If you offer unregistered users the option to subscribe to a communication channel, you should query the emailAccounts database, which contains both unregistered and lite users as well as registered users.

Query examples:

  • Retrieve all subscribers to a specific subscription, from email accounts:

    SELECT * FROM emailAccounts WHERE subscriptions.<SUBSCRIPTION-NAME>.email.isSubscribed=true
  • Retrieve all subscribers to a specific notifications stream, whose double opt-in status is "Confirmed", from email accounts:

    SELECT * FROM emailAccounts WHERE subscriptions.<NOTIFICATIONS-NAME>.email.isSubscribed=true AND <NOTIFICATIONS-NAME>.email.doubleOptIn.Status=Confirmed
  • Retrieve all subscribers to a specific subscription, from fully registered accounts:

    SELECT * FROM emailAccounts WHERE subscriptions.<SUBSCRIPTION-NAME>.email.isSubscribed=true AND subscriptions.<SUBSCRIPTION-NAME>.email.hasFullAccount = true
  • Retrieve all subscriptions for an email address: 

    SELECT * FROM emailAccounts WHERE profile.email="<EMAIL-ADDRESS>"
  • Retrieve all subscribers that subscribed prior to a specific date/time:

    SELECT * FROM emailAccounts WHERE subscriptions.<SUBSCRIPTION-NAME>.email.isSubscribed = true AND lastUpdatedSubscriptionState < "2017-11-25T17:09:20.3907174Z"
  • Import and Export Subscription Data Using IdentitySync

    If you would like to import subscription data as part of fully registered accounts, see RaaS Import Guide

    Importing subscription data as part of lite regitrations, can be done using the accounts.importLiteAccount API. 

    If you are using IdentitySync, you can create a dataflow that retrieves subscribers, by using the datasource.read.gigya.account script, and writes them to the email service provider (ESP) you are using. For a list of supported ESPs, see ESP-Marketing Automation-Notification

    Click below to see sample dataflows between Gigya and Mailchimp, that implement Lite Registration features.

     Click to see a sample flow that exports subscribers from Gigya to Mailchimp
    {
     "name": "Mailchimp - Outbound",
     "description": "account > rename > remove > mailchimp",
     "steps": [
      {
       "id": "account",
       "type": "datasource.read.gigya.account",
       "params": {
        "batchSize": 300,
        "deltaField": "created",
        "excludeEmptyFields": false,
        "from": "emailAccounts",
        "maxConcurrency": 1,
        "select": "*",
        "where": "subscriptions.SUB-ID.email.isSubscribed = true" AND "subscriptions.SUB-ID.email.doubleOptIn.status = Confirmed"
       },
       "next": [
        "rename"
       ]
      },
      {
       "id": "rename",
       "type": "field.rename",
       "params": {
        "fields": [
         {
          "sourceField": "profile.email",
          "targetField": "EMAIL"
         },
         {
          "sourceField": "subscriptions.SUB-ID.email.isSubscribed",
          "targetField": "NEWSLETTER"
         },
         {
          "sourceField": "profile.firstName",
          "targetField": "FNAME"
         },
         {
          "sourceField": "profile.lastName",
          "targetField": "LNAME"
         },
    	 {
          "sourceField": "subscriptions.SUB-ID.email.doubleOptIn.status",
          "targetField": "DOI" // Custom field created in Mailchimp for the double opt-in status
         },
         {
          "sourceField": "token",
          "targetField": "CTOKEN"
         }
        ]
       },
       "next": [
        "remove"
       ]
      },
      {
       "id": "remove",
       "type": "field.remove",
       "params": {
        "fields": [
         "profile",
         "data",
         "subscriptions"
        ]
       },
       "next": [
        "evaluate"
       ]
      },
      {
       "id": "evaluate",
       "type": "field.evaluate",
       "params": {
        "fields": [
         {
          "expression": "'ronen'",
          "field": "SUBID"
         }
        ],
        "language": "jexl"
       },
       "next": [
        "mailchimp"
       ]
      },
      {
       "id": "mailchimp",
       "type": "datasource.write.mailchimp",
       "params": {
        "apiKey": "33911ab9049868defee1aba1c5551532-us15",
        "apiUrl": "https://us15.api.mailchimp.com/3.0/",
        "listId": "...", // the Mailchimp listID
        "maxConnections": 10,
        "newsletterField": "NEWSLETTER",
        "retryIntervalSeconds": 10,
        "maxRetry": 30,
        "timeout": 120
       }
      }
     ]
    }
     Click to see a sample flow for importing subscribers from Mailchimp to Gigya
    {
     "name": "Import from Mailchimp",
     "description": "mailchimp inbound",
     "steps": [
      {
       "id": "mailchimp",
       "type": "datasource.read.mailchimp",
       "params": {
        "apiKey": "...", // Mailchimp API key
        "apiUrl": "https://us15.api.mailchimp.com/3.0/",
        "batchSize": 100,
        "listId": "...", // Mailchimp list ID
        "maxConnections": 10,
        "retryIntervalSeconds": 3,
        "timeout": 120
       },
       "next": [
        "evaluate_subscribed"
       ]
      },
      {
       "id": "evaluate_subscribed",
       "type": "field.evaluate",
       "params": {
        "fields": [
         {
          "expression": "status eq 'subscribed' ? true : false", //Transform the Mailchimp "subscribed" status to a "true" value in Gigya's Boolean subscription status field
          "field": "subscriptions.SUB-ID.email.isSubscribed"
         }
        ],
        "language": "jexl"
       },
       "next": [
        "rename"
       ]
      },
      {
       "id": "rename", //Rename Mailchimp fields to a Gigya format
       "type": "field.rename",
       "params": {
        "fields": [
         {
          "sourceField": "email_address",
          "targetField": "profile.email"
         },
         {
          "sourceField": "merge_fields.CTOKEN",
          "targetField": "token"
         },
         {
          "sourceField": "merge_fields.FNAME",
          "targetField": "profile.firstName"
         },
         {
          "sourceField": "merge_fields.LNAME",
          "targetField": "profile.lastName"
         }
        ]
       },
       "next": [
        "gigyaGenericWriter"
       ]
      },
      {
       "id": "gigyaGenericWriter",
       "type": "datasource.write.gigya.generic",
       "params": {
        "apiMethod": "accounts.importLiteAccount",
        "apiParams": [
         {
          "paramName": "profile",
          "sourceField": "profile"
         },
         {
          "paramName": "email",
          "sourceField": "profile.email"
         },
         {
          "paramName": "subscriptions",
          "sourceField": "subscriptions"
         }
        ],
        "maxConnections": 10
       }
      }
     ]
    }

    Importing the double opt-in object is not yet supported when using accounts.importLiteAccount. The import will succeed, but no double opt-in data will be written.

     

    Frequently Asked Questions

     In a site group implementation, can users see their subscriptions to the newsletters of all sites in the group, or just the one they're currently on?

     That depends on your implementation.

    Users can see their subscriptions and subscription statuses in the "profile update" screen. If you want to display only the subscriptions of site A, you should have a dedicated "profile update" screen for site A and include in it only the relevant subscriptions for that site. If you wish to display to users their subscriptions for all brands in the group, have a centralized "profile update" screen that is shared by all sites and includes all the available subscriptions.

     Double opt-in: what happens if a user subscribes, confirms, then cancels?

     The double opt-in status is set to “NotConfirmed”, and the ConfirmTime is reset to “null”.

     Double opt-in: can I see at what time the confirmation email was sent?

    Yes, the doubleOptIn object includes an EmailSentTime parameter that is updated automatically when the email is sent.

     Can Subscription Management be localized?

    You can localize the following aspects of subscription management:

     Double opt-in: What happens if a form includes both single and double opt-in subscriptions?

    In this case, the user will receive a confirmation email that lists only the Double Opt-In subscriptions they checked in the screen. While Gigya fully supports having a mix of single and double opt-in subscriptions on the same screen, it is not the recommended or common implementation.