A Temporary Way to Change Screen Text in Hosted Login v2

Hosted Login v2 introduces a new way of managing your screens. In the v2 version of Hosted Login, you still need to specify a flow; if your application client doesn’t include the default_flow_name setting your authentication requests will all fail with the following error:

But while the flow is still important, and still required, a large portion of v2's screen management actually takes place outside the flow. For example, Hosted Login introduces a number of new screens and new JTL (Janrain Templating Languages) tags, and neither those new screens or those new JTL tags are in your existing flow. But that’s not a problem: because v2 screens and screen text are managed outside of the flow you can still render new screens such as this one:

That’s great: that means you can start using Hosted Login v2 right away, and without having to update your flow. At the same time, however, this does leave an important question unanswered. In Hosted Login v1, you can change the text displayed on screen by changing the translation associated with a given JTL tag. As you know, translations are stored in the flow. However, Hosted Login v2 introduces a number of new JTL tags that aren’t stored in your flow. Does that mean that there’s no way to change screen text in Hosted Login v2? Or at least no way to change the new, v2-only screen text?

For better or worse, we’re going to provide several different answers to that question. To begin with, most of the JTL tags used in Hosted Login v2 are unchanged from Hosted Login v1. Those tags can readily be changed in your flow; do that, and the value of the tag as defined in your flow is the value used to redner your screen text. For example, by default the heading for the Hosed Login sign-in screen (JTL tag textSignInScreenHeading) reads Welcome to Gizmo:

If you don’t like that you can use the Console or the /config/{appId}/flows{flow}/translations endpoint to change the value to something else:

Works like a charm, and in Hosted Login v2 as well as Hoisted Login v1.

That’s one answer. Another answer is this: API endpoints are in development that will soon make it easy to copy all the new Hosted Login v2 tags to an existing flow. With that mind, answer no. 2 is this: no, you can’t modify the new JTL tags at the moment, but that will change in the near future. You just need to be patient.

But what if you can't be patient? Well, in that case, we have a third answer. This is not officially supported, but you can add the new JTL tags to your flow and then change those tags. For example, by default the new textAuthRuleSecondFactorHeading JTL tag is set to 2FA Required:

However, we were able to add, and then change, that JTL tag so our screen now reads like this:

If you’re going to experiment with changing v2 JTL tags we recommend that you do it on a backup version of your flow; that way, if anything goes wrong, you can simply point your application client to the original version of the flow and go back to business as usual.  That way, too, when the new API endpoints are released you can. if necessary, discard the backup copy of your flow and run those APIs against your “real” flow. If you manually add JTL tags to a flow will those tags created problems for the forthcoming API endpoints? We can't say for sure, which is why this is a use-at-your-own-risk proposition. 

And why it's a good idea not to do this on your primary flow.

If you want to give this a try, you can add a new translation (i.e., a new JTL tag) by completing the following procedure in Console:

  1. Click Registration Builder, click the Actions icon next to the flow used by your application client, and then click Edit:

  2. On the home screen for the flow, click Fields and then click Create Field:

  3. In the Choose a Schema Attribute for your new field dialog, select a schema and a schema attribute from the two dropdown lists and then click Next: Field Details:

    Interestingly enough, it doesn’t matter which schema and schema attribute you select; that’s because the new translation won’t actually be tied to a schema or to a schema attribute. However, Console won’t let you proceed unless you choose something from both the Schema Select and the Select an Attribute dropdowns.

  4. On the Create Field page, enter the JTL tag in the Name field:

    For information about the JTL tags used on the new Hosted Login v2 screens, see the Hosted Login v2 Screen Reference.

  5. Select Translatable String from the Field Type dropdown:

  6. Enter the new text for the translation in the Value field and then click Save Changes:

And that’s it. Now you just have to wait a minute or two for your changes to take effect:

This is probably the fastest and easiest way to add new translations to your flow. (The other way to do this? Use the POST method and the /config/{appId}/flows/{flow}/translations endpoint.) And if you want to restore the old text? That’s fine; it’s easy enough to edit the field and restore the old value:

Or, you can simply delete the translation. If the translation is deleted then Hosted Login reverts to the values found in the master flow.