Web Snippet API

Overview

Yozio provides the Web Snippet to use in tandem with the SuperLink to achieve maximal control over your user's redirect experience. With the Web Snippet, you can implement features such as forced click (autoRedirect), app install detection (detectNewInstall), and web to app campaigns (redirectOnClick). Additionally, using the Web Snippet will allow you to mask the redirect, so users will never see "deeplink.yozio.com" or other redirects when they click on a SuperLink.

Web Snippet Functions

Yozio.onPageLoad(args)

You must call Yozio.onPageLoad(args) during the onload of any page that you will put a Yozio SuperLink on. This will initialize Yozio Web Snippet and load required resources accordingly. List the short urls of all the Yozio SuperLinks you plan to use on the webpage.

1
2
3
4
5
6
7
8
<body>
<script type="text/javascript">
Yozio.onPageLoad({
  shortUrls: [
    "kg.c.kW"
  ],
});
</script>

shortUrls (required) is a list of short urls that you will place on current page

In addition, you can pass additional arguments to onPageLoad to control user flow. For example, you can use the autoRedirect object to determine if a user will automatically be redirected when they visit the webpage.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<body>
<script type="text/javascript">
Yozio.onPageLoad({
  shortUrls: [
    "kg.c.kW"
  ],
  autoRedirect: {
    url: "https://r.yozio.com/kg.c.kW",
    params: {
      utm_source: "mweb",
      forged_of':"mithril_and_steel"
    },
  }
});
</script>

The autoRedirect object has a couple of attributes

  • url (required) - this should be your Yozio link ie https://r.yozio.com/a.b.c. Metadata can be attached directly https://r.yozio.com/a.b.c?utm_campaign=giftideas&one_ring_belongs_to=sauron
  • params (optional) - a javascript dictionary object containing your metadata key value pairs. Acceptable values: null,{}, {'forged_of':'mithril_and_steel','utm_source':'mweb'}.

Finally, if the page is pointed to by a Universal Link, you must include the onUniversalLinkPage flag

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<body>
<script type="text/javascript">
Yozio.onPageLoad({
  shortUrls: [
    "kg.c.kW"
  ],
  autoRedirect: {
    url: "https://r.yozio.com/kg.c.kW",
    params: {
      utm_source: "mweb",
      yozio_use_custom_scheme_in_safari: true 
    },
  }
  onUniversalLinkPage: false
});
</script>

Yozio.redirectOnClick(url, params)

After implementing Yozio.onPageLoad(args) you may call Yozio.redirectOnClick(url, params) to redirect the end user when they interact with your webpage:

1
2
<a href="#" onClick="Yozio.redirectOnClick('http://r.yoz.io/lp.c.C',
{yozio_ios_universal_link_redirect_url:'https://www.example.com/path_configured_for_ios_universal_link'});">Open in App</a>

Note that yozio_ios_universal_link_redirect_url is a required dynamic metadata key that you must provide if the URL being redirected to is configured for Universal Link. It will be automatically ignored if the end user is not on iOS 9.

Additionally, note that we give you the optional params field. This allows you to attach metadata to the SuperLink that the user is automatically routed to. This is the only way to dynamically attach metadata. All statically attached metadata (entered in the Yozio Console) will still be attached, but there is no opportunity to dynamically attach metadata to the end of the SuperLink otherwise.

Yozio.detectNewInstall(afterInstalledDetectionCallback)

If you have set up Universal Link on your domain, we have provided a function that takes a callback function. Yozio.detectNewInstall will pass a boolean isAppInstalled to this function. 'Yozio.detectNewInstall' will take in a function, afterInstalledDetectionCallback, and call that function with parameter isAppInstalled, a boolean that is true when the app is installed (the Universal Link native banner is detected), and false otherwise.

For example, you can define a function,

1
2
3
hideCustomBannerIfUniversalLinkBannerDetected = function(isAppInstalled) {
    \\code that hides the custom banner
}

that hides your custom implemented banner if isInstalled == true. You can then call Yozio.detectNewInstall(hideCustomBannerIfUniversalLinkBannerDetected), which will pass isAppInstalled to your function. Implemented this way, if you have Universal Link set up, your users will not see two banners if they have the app installed.

Note that this function can only detect an app install when the user is on iOS 9, browsing with Safari. This function will not detect the app install for users on iOS 8 and older, or those who are using other browsers, such as Chrome or Firefox.

Web Snippet Parameters

If you wish to have Universal Links triggered then the end user may interact with Yozio short url directly ie https://r.yozio.com/a.b.c, i.e on 3rd party website, you must use yozio_ios_universal_link_redirect_url to pass a Universal Link compatible URL ie https://r.yozio.com/a.b.c?yozio_ios_universal_link_redirect_url=http://www.example.com/product/123. Doing so will tell Yozio to forward users who click on this SuperLink to your yozio_ios_universal_link_redirect_url and trigger Universal Links.

By Apple's design, Universal Links will launch your app for users who have your app and take those who don't have your app to the web URL you have specified as the value for yozio_ios_universal_link_redirect_url. From here, you may leverage the Yozio Web Snippet functions to handle the redirect of users who do not have your app or have clicked the forward button provided by Apple Universal Links to "opt out" of Universal Link deep linking.

Other notes:

  • You may use also use Yozio SuperLink and/or Sublink API to create a new short url with yozio_ios_universal_link_redirect_url key.
  • By default yozio_use_custom_scheme_in_safari is set to true. Thus, if you do not pass yozio_ios_universal_link_redirect_url and have configured your SuperLink to redirect users who have your app to be deep linked via custom scheme, Yozio will use custom scheme to try to deep link your iOS 9 users.

Web Snippet v1.3 flags

Finally, with the release of Web Snippet v1.3, we've added new flags to better control user flow. These flags are particularly powerful for handling users on iOS 9.

  • yozio_use_custom_scheme_in_safari. By default this is set to true; As long as this flag remains true user will be able to deep link using custom scheme into the application, given that Deep Linking through custom scheme is configured for your SuperLink (You can configured this through the Yozio Console Edit SuperLink > Redirect Settings > DeepLink User? > enter the custom scheme you have configured). If you wish, you may tell Yozio not to use this method of deep linking for your iOS 9 users by setting yozio_use_custom_scheme_in_safari = false. To do this attach yozio_use_custom_scheme_in_safari = false to your SuperLink as metadata
  • Also included are the Yozio.onUniversalPage flag and the Yozio.autoRedirectUrl object. The onUniversalPage simply denotes whether or not the app has Universal Links configured. The Yozio.autoRedirectUrl object will automatically redirect users to the given URL when a user clicks the link. Both of these snippets can be added to our web snippet OnPageLoad block.
Flag Where to set? Acceptable Values Default Value Impact on User Flow
yozio_ios_universal_link_redirect_url Pass as metadata key value pair The Universal Link URL you have configured Undefined Tells Yozio the Universal Link URL, deep links user if they have app
yozio_use_custom_scheme_in_safari Pass as metadata key value pair true, false true Allows you to redirect users to your custom scheme URL
yozio_disable_new_install Pass as metadata key value pair true, false false Disallows users to install your app (redirects away from app store)
Yozio.onUniversalLinkPage Assign value in onPageLoad true, false, passed in OnPageLoad false Allows for redirecting users to custom scheme
Yozio.autoRedirect Assign value in onPageLoad Object passed in OnPageLoad Undefined Allows for automatic redirecting of users to custom scheme

Web Snippet Setup

Masked Redirect

In order to set up the masked redirect, all you have to do is set up Yozio.onPageLoad(args) with the short url information attached to it. You can use any of the flags (such as onUniversalLinkPage, or autoRedirect) as needed. Once you've done this, configure the button/link that the user will click with Yozio.redirectOnClick. This will then route all clicks made to this button using the Yozio SuperLink you enter, and the user will see an improved redirect experience. See the code example below for a simple implementation.

1
2
3
4
5
6
7
8
<body>
<script type="text/javascript">
Yozio.onPageLoad({
  shortUrls: [
    "kg.c.kW"
  ]
});
</script>

Forced Click

In order to set up forced click, use the autoRedirect function we provide. After you implement Yozio.onPageLoad and configure it with the SuperLink you want to route users to, simply implement the autoRedirect function. See the example below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<body>
<script type="text/javascript">
Yozio.onPageLoad({
  shortUrls: [
    "kg.c.kW"
  ],
  autoRedirect: {
    url: "https://r.yozio.com/kg.c.kW",
    params: {
      utm_source: "mweb",
      yozio_use_custom_scheme_in_safari: true 
    },
  }
});
</script>

Note that you will not need to implement Yozio.redirectOnClick, since the user is forced clicked when they reach your webpage. However, we recommend you doing so, in the event that the user chooses to go back to the webpage instead of continuing in the app. This way, any buttons they click will further attempt to redirect your users to the app.