Managing Multiple Sites and Brands

By default, the standard registration experience includes the standard Flow and user entityType, and for most cases this suffices. However, when managing the complexity that comes hand-in-hand with multiple brands, sometimes it is necessary to implement additional Flows and entityTypes.

When should I create multiple flows?

If one of the below scenarios applies to your brand/site, then you may want to consider creating another copy of your Flow:

  • Brand A requires pieces of information that should be optional for Brand B
  • Your sites/brands are very different aesthetically, and you use Janrain’s transactional emails

You can copy a Flow by making a POST request to the /config/{app}/Flows/{Flow}/copy Configuration API endpoint. Then, you can reference this new Flow at your site via the flowName and flowVersion settings:

janrain.settings.capture.flowName = "myNewFlow";
janrain.settings.capture.flowVersion = "01234567890123456789";

The following subsections describe the above use cases in more detail.

Brand A requires pieces of information that should be optional for Brand B

Suppose you have site A and site B. Site A requires birthdate, but site B does not. Suppose that, in order to fulfill the requirements of site A, you have created a birthday field that has the required validation rule.

At first consideration, in order to fulfill the requirements of site B it may seem like a good idea to create another birthday field that doesn’t have the requiredvalidation rule (let’s call this field “birthdayOptional”), and then to exclude the required birthdate field on site B.

Unfortunately, this would not work. Although Site A uses the “birthday” field and site B uses the “birthdayOptional” field, both sites use the same registration form in the Flow. Therefore, while site B may exclude the JTL tag markup on the registration screen for the required version of the birthday field, the registration form in the Flow still expects this field to be submitted to it. Since this “birthday” field has the required validation rule, then registration will always fail with validation errors on site B.

One alternative may be to make both fields optional, and then to implement your own client-side JavaScript validation on site A where birthday is required. However, this approach excludes server-side validation (not a recommended practice). Therefore, it is better in these cases to create a copy of your existing Flow, add/remove/modify fields on the new Flow, and then direct each site to the respective Flow.

Your sites/brands are very different aesthetically, and you use Janrain’s transactional emails

A single Flow assumes the same general look and feel for email templates across all sites–for instance, maybe the registration confirmation email has a 3-column horizontal layout with a title and body. The email template then may include JTL tags that allow variation in images, welcome messages, or values for style elements in order to give each site a different feel/appearance.

However, what if you want to have a registration confirmation email for Site A that has a 3-column layout, but for Site B you want to have a single-column layout?

Since a single Flow only allows only one template across sites for each transactional email type, then both sites would need to share the same template. At first glance, putting HTML into API client settings and then referencing those in your emails may seem like a feasible solution. However, this approach is not recommended; API client settings values are escaped and printed as plain text.

Therefore, if you wish to achieve dramatically different email template layouts for each site the best approach is to create a copy of your Flow and modify the email templates in the new Flow.

Alternatively, also considering utilizing third-party email integrations if your transactional email solution requires a high degree of customization.

Why might I implement multiple entityTypes?

If one of the below scenarios applies to your sites/brands, then you may want to consider creating a new entityType:

  • Sites A and B are two drastically different brands; it would be too complex to incorporate all brand structures into one schema for user profile data
  • You wish to segment users from Site A and users from Site B and therefore cannot have data in common between the two sites
  • You do not want your users to view brands as associated with each other; for instance, sharing the same login experience between child and adult brands.
  • Site A has special membership validations and users from siteB shouldn’t be able to login with their profile from siteB. A common example is meeting legal agreements for doctor-login portals between countries.

Generally speaking, To implement multiple entityTypes, you need to change both the Flow and the API client settings in the Janrain Console, in addition to creating your new entityType.

  1. Create your new entityType by making a POST call to the /entityType.create Capture endpoint. If you want to copy an existing entity and modify it, you can do this by copying the attr_defs object from a GET request on the desired entityType. You must not include the id or uuid attributes, as these are automatically created with the new entityType. Below is an example value for the attr_defs URL parameter, which creates an entityType with the “name” and “description” attributes.
[
  {     
    "name":"name",
    "type":"string",
    "case-sensitive":false   
  },   
  {
    "name":"description",
    "type":"string",
    "length": 1000,     
    "case-sensitive":false   
  } 
]
  1. In the Flow, add the list of entityTypes to the schemas object in the Flow. Below is an example PUT request adding the entityType user_2 to the Flow. Note, make sure to include in your request all entityTypes that this flow may be used with, not just the entityType you wish to add.
{
  "userData": [
    "email",
    "displayName"
  ],
  "schemas": [
    "user",
    "user_2"
  ]
}
  1. In your API client settings add the user_entity_type setting to all clients to specify the entityType each uses.