OneLink™ 1/4: Converting users from owned media

At a glance: Use this guide to create a link to send new users who don't have your app to the relevant store or web page, depending on their platform. If the AppsFlyer SDK is installed on your app, the users are attributed to the correct source—including to your owned media, such as banners, emails, SMS campaigns, or QR codes on posters.

Part1_180X408.png Part2_fade_180X408.png Part3_fade_180X408.png Part4_fade_180X408.png

Scope of work

Who's involved

Only the marketer is required.

If the AppsFlyer SDK is already installed, you can complete this guide entirely using the AppsFlyer dashboard, without a developer making any changes to your app's code.

Prerequisites

  • An AppsFlyer account with at least one app.
  • For attribution: The AppsFlyer SDK already installed in each of your mobile apps.
    • If the SDK is not yet installed in your apps, it is still possible to create a working redirection link, but it will not be possible to measure installs in your dashboard, deep link, or deferred deep link.

Time required

Approximately 30 minutes

Outcome

  • Users clicking the link will be sent to the correct app store or web page based on their device.
  • Users will be attributed from the click/install to your owned media sources.

 Example

Mark is the marketer of a successful grocery delivery service called "Feed Me". Mark targets his user-base phone numbers to download Feed Me's new mobile iOS and Android apps. An SMS campaign is planned, targeting registered users who have not yet installed the app. However, Mark doesn't know which users have Android or iOS devices.

To solve this, Mark sends the SMS containing a short URL powered by OneLink. When a user receives the SMS and clicks the link, it automatically directs them to the appropriate app store or landing page, where it's easy for them to install the app.

These new installs are attributed to the SMS campaign, enabling Mark to check the success of the SMS campaign in AppsFlyer. 

Procedures

Complete the following procedures to set up a custom link that:

  • Directs users to the correct app store or web page based on their device.
  • Attributes the click/install to your owned media source.

1. Creating a OneLink template

A OneLink template represents the routing logic at the core of your links. A OneLink template is not a clickable link for your end-users; it is the foundation for generating many custom links. A OneLink template is where you record your decisions on how to redirect users, based on their platform, and on whether they have your app installed.

A single OneLink template can be the basis for creating many links, as we'll see later in this guide. It is rare to need more than one or two OneLink templates in the lifetime of an app (outside of testing).

To create a OneLink template:

  1. In the AppsFlyer dashboard, go to Engagement & deep linking > OneLink Custom Links.
    OneLink is an account-level feature, which lets you create OneLink templates and their custom links for all your apps.
  2. In the top left corner of the page, click on Add OneLink template.
    The OneLink template setup page opens.

    OneLink_template_page_en-us.png

  3. In the OneLink template name field, enter a name.

     Note

    • A good OneLink template name includes the name of the app (e.g. feed_me) or the use case or experience represented by the OneLink (e.g. pre_launch_landing_page).
    • The name should not include the campaign or channel name or media source (since this isn't the actual end-user link, just the underlying template to create many links), or the name of the platform (Android, iOS, since multiple platforms are usually the reason for using a OneLink template in the first place).
    • This template name is only used internally. It doesn't affect your marketing attribution data and is not seen by users.
  4. In the Subdomain field, enter your subdomain name.
    • Choose a subdomain that matches your brand. For example, if your website is www.acme.com choose acme as your subdomain.
    • Only use lower-case letters, digits, or hyphen (-).
    • OneLink also supports fully branded links. Learn more
  5. Select your Android app, iOS app, or both. This takes care of redirecting clicking users without your app to the correct App Store. 

    • [optional] Change to a different URL: In some cases, you may prefer to take new users to a mobile web experience rather than directly to the app store (or your app may not be listed in the store). To implement, enter that URL in the Landing page URL field.
    • If you've selected an Android app and an iOS app, the template is configured to send new and existing users to their respective destinations.
    • If you've selected only one app, Android or iOS, the template is configured to send ALL users (iOS and Android, new and existing) to the single defined destination.
  6. Skip When app is installed. This is discussed in the next guide.
  7. [optional] Change destination for When link is clicked on desktop.
    • In some cases, your link might be clicked on a desktop computer, especially if it is sent via email or social media. If you expect a lot of desktop traffic to your link, you might want to send those users to a landing page or the main website homepage, or a page where they can request an SMS link on their phone, instead of the relevant app store.
    • By default, desktop users are redirected to your app's iOS App Store page, or to Google Play's app page, If an iOS app isn't defined.
  8. [optional] Select apps from other platforms
    If you have a dedicated app version for the following:
    • Windows phone - activate toggle and select app or Change to a different URL.
    • iPad - activate toggle and select iPad app
    • Amazon Kindle Fire - activate toggle and add Amazon store ASIN or app page URL.
  9. Click Save OneLink template (Update OneLink template for edited templates). 
    Your OneLink template is now created and can be used to create many different clickable links (see the following section).

2. Creating a custom attribution link for users

The OneLink template is ready! Now it's time to add a custom link to attribute users to an owned media campaign. Setup the custom link to get the URL to share with your users. 

To create a custom link based on the OneLink template:

  1. In the AppsFlyer dashboard, go to Engagement & deep linking > OneLink Custom Links.
  2. Select the OneLink template to add a custom link for.
    • New template - Click Add custom link.
    • Template with defined links - Click Add custom link or click on a Custom link name in the list to edit it.
  3. The Custom link page opens. 

    Add_custom_link_en-us.png

    The page header shows the apps set for the custom link, based on the OneLink template it belongs to. Click on the links in the header to head back to the list of OneLink custom links of this OneLink template.
  4. In the Custom link name field, enter a name.
    • Choose a name based on why you are creating the link, or who you are sharing it with. 
  5. In the Short URL field:
    • If you have one or more Branded links, select it from the drop-down.
    • Set the short URL slug to a specific value, or leave the default value as it is.
  6. In the Attribution tab, you can select the parameters to attribute clicking users to a media source, campaign, channel, etc.  
    • Click on one of the suggested Owned media sources (e.g. SMS) or click on Custom to set a different name. The selected name is the Media source name, under which all clicking users' data is collected. Read more about selecting a good custom media source name.
    • Select a Campaign name (e.g. summer 2020). This enables you to compare different campaigns under the same owned media source.
      Note: For the purposes of getting started or testing your link, name the media source 'test' and name the campaign 'getting started guide'.
    • Skip the Retargeting campaign toggle. We cover it in the following guide.
    • Click Add parameter to add more attribution parameters, such as Ad set name, Ad name, Channel, your own custom parameters, or 1-5 Subscriber parameters. This enables a more granular analysis of your marketing efforts. Read more about the additional attribution parameters.
    • [optional] Change the Click-through Lookback window value. Activate toggle to reveal the slider and set a Lookback window, 1-23 hours, or 1-30 days. If deactivated, the default value is 7 days. 
    • [optional] Set a fixed Cost per install. Select the currency and amount that each new install costs you. This enables you to see the ROAS of your owned media campaigns.
  7. Skip the Redirecting & deep linking and Social app landing page tabs.
    They will become useful when we enable deep linking, in the next guide.
    However, ONLY if you wish to override the template's configured redirections for users that don't have the app installed, you can do it in the Redirecting & deep linking tab.
  8. Click Generate Link.
    A short URL and long URL are displayed, each with a corresponding QR code.

3. Testing

To test your link:

  1. Prerequisites: a whitelisted device without the app.
  2. In the AppsFlyer dashboard, go to Engagement & deep linking > Link management.
  3. Hover over the Actions icon of the link you want to test and click Get URL
  4. Send the short or long URL to your phone. You can either:
    • Scan the QR code with your phone camera or QR scanner app.
    • Email or WhatsApp yourself the link, and open it on your phone.
      Note: Do not paste into iOS notes, or directly into a mobile browser. Often, the mobile operating system intentionally will not open the app in this context.
  5. Click the link on your mobile device.
    Depending on your platform, it should take you to the app store or landing page.
    Note: A real click on a mobile device is needed. Javascript or 301/302 redirects can't trigger Universal Links and Android App Links. Even basic redirections fail with these methods on some browsers.
  6. Download and launch the app.
  7. In the AppsFlyer Overview dashboard look for a new organic install.
    Look for a new click and install under media source (e.g. test) and the campaign name you put in the URL.

If you completed all three procedures in this article, then congratulations! You have created a link you can send to all new users who do not have your app and direct them to the correct app store.

 

OneLink_pic.png

 

The following sections contain various FAQs and general explanations about OneLink. 

OneLink parameter FAQs

What can I use as a custom media source name?

Integrated Partner reserved pid values (ending with _int), cannot be used as media source values in Custom Attribution Links. Use the Integrated Partners setup to create partner-related attribution links. For more details, click here.

Do not use "Facebook," "Facebook Ads," "GoogleAdwords," "Twitter," or "Organic" as your custom media source name (case insensitive). Using these names for custom attribution links may affect attribution data integrity, as installs from your owned media would get attributed to integrated partners.

Additional attribution parameters

You can add further attribution parameters to enable you to perform a thorough drill-down analysis. 

Attribution parameter Description Parameter link name
Campaign Add it to compare different campaigns within the owned media source c
Adset Set ad set names to compare different ad sets within specific campaigns of the media source af_adset
Ad Name

Set ad names to compare different creatives within specific ad sets/campaigns of the owned media source

af_ad
Channel Set channel names if you have more than one distribution channel for your owned media that you want to compare. For example, if you split SMS messages between two SMS service providers, specify on the channel parameter which provider it is. Later, you can compare conversion rates to decide on the better provider af_channel
Subscriber Parameters Use any of the 5 subscriber parameters to insert useful values. Note that these parameters get parsed and appear in the raw data report, which makes them useful for performing data aggregation or filtering af_sub1, af_sub2, af_sub3, af_sub4, af_sub5
Custom Parameters Similar to subscriber parameters, you can use fields with any values and any names. However, these are not parsed and made available on the raw data reports; only as part of the full original URL

Custom

See more information about AppsFlyer's Attribution Link Structure and Parameters.

Customized Lookback Window

Enabling the Customized Lookback Window button allows you to set the maximum click to install time. Installs (first launches) that take place within the lookback window are attributed to the media source. Installs that take place afterward, are attributed as Organic.

By default, the window is set to 7 days, but you may wish to set it otherwise in different cases.

 Example

A regular 7-day lookback window for email campaigns is reasonable. However, if an email contains an attractive and memorable video, it makes sense to extend its lookback window to 14 days.

More details about click lookback windows here.

Cost per install

Enabling the Cost per install button allows you to apply a specific CPI value for each install coming from the link.

Select the cost currency and then a numeric ONLY value (float - up to 4 digits after the decimal point) representing the CPI.

 Example

An SMS campaign costs $20 per 1000 messages (CPM). From your experience, these campaigns achieve a 5% conversion rate, meaning the derived CPI is $1. Setting the cost per install to 1 USD enables you to easily see the eventual ROI of the SMS campaign.

More details about measuring cost and ROI here.

Attribution link parameters: af_cost_currency, af_cost_value

Are parameter names case-sensitive?

Yes. When you set parameters on the attribution link, make sure that you use consistent naming. Do not use upper and lower case names intermittently.

If you don't keep the same case in parameter names, it might cause issues with viewing data in the dashboard and raw data.

For example, if you set pid=MyMediaSource on one attribution link and pid=mymediasource on another, discrepancies in data may occur. The same goes for any other param that you set on the attribution link. If you choose a case, upper or lower, make sure you always use it.

Preventing parameter forwarding on redirections

af_raf_ios_urlaf_android_url, and af_web_dp carry parameters from the attribution link or OneLink over to the redirected page. To prevent such parameters from being carried over to the redirected page, add af_param_forwarding=false to the attribution link.

Are single-platform custom links still available?

OneLink is now the only supported method for creating custom attribution links for owned media.
In the past, app owners could also use single-platform (app-specific) custom links without using OneLink. This method is deprecated, and new custom links can only be created based on a OneLink template.
However, if you have legacy single-platform custom links, they still work as always. You can also view and edit your legacy links, by clicking the View legacy single platform links link, on the top right corner of OneLink Custom Links page.

Integrated partner FAQs

Using OneLink URLs in social apps (unpaid)

Advertisers may want to use OneLink with "viral" posts on social apps, as potential users that are exposed to such posts cannot be targeted in advance according to their devices.

Unfortunately, limitations set mainly by Apple's Universal Links, in conjunction with restrictions of some of the social apps, complicate the use of OneLink for deep linking, and sometimes even for basic device recognition, redirection and attribution.

The following table summarizes what you can do with OneLink in today’s popular social apps:

Social app Android redirection Android deep linking iOS redirection iOS deep linking
Facebook ✓* ✓* 
Facebook Messenger ✓*  ✓* 
Snapchat ✓*  ✓* 
Instagram -
Reddit - - - -
Slack ✓*  ✓* 
Twitter ✓*  ✓* 
WeChat
(See WeChat FAQ)
- - -
Whatsapp
If URI scheme is used instead of App or Universal link, or if you set a landing page.

Using OneLink with integrated networks (paid)

OneLink is mainly used with owned media; not with ad networks.

It is rare for ad networks to require OneLink since they usually advertise on apps. This enables them to know the user's platform, device ID, etc., so their app and platform-specific attribution links suffice.

However, sometimes ad networks don't know the users' platform in advance—for example when they run email or SMS campaigns themselves.

 Important!

OneLink with integrated networks requires you to use the OneLink long URL.

To setup OneLink for partner ad networks:
  1. Go to Integrated Partners on your Android app's dashboard and select the relevant ad network.
  2. Copy the app's attribution link from the setup window, and save it to an external document.
  3. For your iOS app, repeat steps 1+2.

Now build the attribution link:

  1. Make sure OneLink is properly set up.
    In the Attribution section,
     use "test" as the media source name.
  2. Click Generate Link.
    The short and long URLs appear.
  3. Copy the long URL.
  4. In the long link, Replace the "test" media source with the exact PID of the integrated partner to the link https://greatapp.onelink.me/U8ru?pid=network_int&c=MyCampaign
  5. Add ALL parameters from BOTH attribution links.
    If the attribution link of the iOS and Android app are identical, simply copy the parameters from either one of the links. Otherwise, make sure you have all the parameters from both links.

If all the integrated network parameters are added correctly, once OneLink is clicked and the user is redirected to the right platform, the required parameters are sent to the network within a postback after the user installs.

 Example

https://greatapp.onelink.me/3287867539?pid=network_int&c=email&
idfa{$IDFA}&gaid={$GAID}&clickid=$SITEID&
af_sub1=[pixel_code]&af_sub2=[creative]

The network uses either the IDFA or GAID parameters according to the client's device platform and disregards the other parameter.

Are there any limitations on posting OneLink on Instagram?

Yes, there are a couple of Instagram limitations:

  • Due to the way Instagram renders the text of a page post, links do not become clickable when entered into a post caption.
  • Linking from profile website links is possible. However, for iOS, it directs to the App Store all the time, since Universal Links are not supported in Instagram.

What is AppsFlyer's solution for Android OneLink redirections on WeChat?

WeChat overrides Android deep links redirecting users to a web page. From the web page, the user must then click the options button and choose to open the page in browser. As a result, users encounter a broken user experience, increasing the chance for them to drop off in the conversion funnel.

To overcome this, OneLink can recognize clicks in WeChat and load a dedicated landing page instructing the user to click the options button and then to click Open in Browser. This opens the redirect URL defined in the OneLink template setup.

WeChat_a.jpg

If the user’s WeChat language is registered as Chinese, OneLink generates a localized version of the landing page:

WeChat_b.jpg

Limitations

What are the length limitations of OneLink URLs?

  • Total URL length must not exceed 2000 characters
  • Link Name and Media Source: must not exceed 100 characters
  • The following characters are not allowed [<>;(){}`']
  • Short URL ID must not exceed 50 characters

Is there any limitation on posting OneLink on web pages?

Yes. Using target="_blank" in the HTML href tag does not result in redirection to Google Play or App Store. If the OneLink URL is placed inside an html a tag with the  target="_blank" attribute, it opens a blank page in Chrome on Android and iOS. This affects OneLink functionality. Make sure that the a tag doesn't include the target attribute.

Next step

Follow the instructions in OneLink guide 2/4 to send existing app users who click your link directly to the app itself.

 

Was this article helpful?