LINE Conversion API v1 (1.0.0)

Development Guidelines

This document provides the guidelines and best practices for developing Conversion API.

Order to send events

When sending events, you should send them in the order that the events occurred in as much as possible.

If you don't send the events in the order that they occurred, the conversion that originally occurred may appear to occur later, or our ad delivery optimization could be affected.

Timing to send events

For more accurate conversion measurements, events should be sent as soon as possible after they occur. In our conversion reporting, we use the time when the event is actually accepted to our server as the time when the conversion occurred.

The expiration dates for our web conversions are as follows:

  • Default conversions: 30 days after user pressed on ad
  • Custom conversions: A custom period you can set between 1 and 180 days

In both LINE Tag and Conversion API, the time when the event is actually accepted to our servers is used as the criteria for the expiration date. For example, even if the conversion event occurred within 30 days since a user pressed an ad, it won't be measured as far as not to send to our server within the term.

Event deduplication

In order to avoid duplicated conversion, events should include a deduplication_key value. Clients may have to send the same event multiple times for the following reasons:

  • A client error, a temporary failure on Conversion API side, or a network error. In these cases, the client must retry sending the event.
  • By sending duplicate events through both LINE Tag and Conversion API, the data that could not be measured via LINE Tag could be complemented with the data from Conversion API. Since the same events are sent from different routes, they will always be sent more than once.
Deduplication Key Flow 2

The unit of fields to be deduplicated

Events can be deduplicated by specifying the deduplication_key field of the event to a unique key that can identify the event. We consider it to be the same event if both events have the same event_name value and deduplication_key value.

Deduplication Key Flow 1

For example, all of the following events are handled as different events and are not subject to deduplication.

{
  ...
  "event": {
    "source_type": "web",
    "event_type": "conversion",
    "event_name": "Conversion",
    "deduplication_key": "key1"
  },
  ...
}
{
  ...
  "event": {
    "source_type": "web",
    "event_type": "conversion",
    "event_name": "Conversion",
    "deduplication_key": "key2"
  },
  ...
}
{
  ...
  "event": {
    "source_type": "web",
    "event_type": "conversion",
    "event_name": "Purchase",
    "deduplication_key": "key1"
  },
  ...
}

Event deduplication period

If multiple events with the same event_name value and deduplication_key value are sent, the events that arrive within 30 days of being accepted for the first time will be deduplicated .

LINE Tag configuration for deduplication

When sending duplicate events through both LINE Tag and Conversion API, it is necessary to set the same deduplication_key to duplicate. To set the deduplication_key in LINE Tag, additional field is required as follows.

_lt('init', {
  customerType: 'lap',
  tagId: '{{ TAG_ID }}',
  deduplicationKey: 'CV_abcdefg'
})

User match

When you send an event via Conversion API, a conversion measurement process is performed to determine whether the LINE ad is attributed to the event. In order to do so, we have to match you and the user who raised the event.

The conversion measurement process via Conversion API uses a user object to match our users. Therefore, the user object must contain at least one field that can be used for user matching. Events where we failed to match users won't be subject to conversion measurement. For details on each field in the user object, please check the request body definition of LINE Conversion API v1 - Send Conversion Event.

Fields available for user matching

Conversion measurement via Conversion API matches users who raised the event with our users, so you need to include field available for user matching as much as possible. The fields available for user matching are:

  • user.line_uid (Recommended)
  • user.click_id (Recommended)
  • user.phone (Recommended)
  • user.email
  • user.ifa
  • user.browser_id
  • user.external_id

The following fields are only available for user matching if we have already created user mapping data.

  • user.browser_id
  • user.external_id

In addition, we will accept the event only if the following two conditions are met.

  • Successful user match in our system
  • The user has consented to our application for our company to collect personally referable information received from the customers as personal data

If the user match fails or if the user's consent cannot be confirmed, the event will be discarded without being processed. If the event is discarded, conversion won't be measured. Please note that the Conversion API status on Business Manager will not be updated, either.

User mapping inside our system

It is recommended to include one of the browser_id or external_id fields in the user object.

By including browser_id orexternal_id, the data used for matching is internally mapped using user data other than browser_id andexternal_id. In this document, we call the created mapping of user data "mapping", and call browser_id and external_id the "mapping keys". The created mapping is also used for conversion measurement by the event sent thereafter. Also, the mapping created via Conversion API is also used for the events sent via LINE Tag and vice versa. All mapping data have expirations dates and are deleted after a certain period of time. It is recommended to update mapping data by sending the latest user data on a regular basis.

The scope where user mapping data is used

  • browser_id is first-party cookie data and is issued to the domain of your website
  • You can set any value for external id. However, mapping with external_id is only available between data sent with the same LINE Tag ID. Also, we internally hash the value, store it and also use when matching.

Server-side tag template configuration guidelines

Introduction

By using the server-side tag template, you can integrate Google Tag Manager and Conversion API to perform server-side tagging.

By integrating, we can measure advertisement effectiveness and user behavior with LINE Tag, as well as measurement through server side containers built on Google Cloud Platform. We currently only support GA4 clients.

For an overview and explanation of server-side tagging, please check the article Server-side tagging on Google Developers.

This guide will explain:

  • How to install server tags using the server-side tag template
  • How to configure server tags based on actual examples
  • About additional fields for server-side tag templates
  • Interoperability between Conversion API and LINE Tag in server-side tagging
  • Precautions

This guide requires basic knowledge of LINE Tag, Conversion API, Google Tag Manager, and server-side tagging. Please check the description of each product for information on these.

Please note that the content of this guide may differ from the latest specifications of Google Tag Manager and server-side tagging. Check the latest documentation for each product to confirm there are no changes or updates.

How to import a server-side tag template

Here, we explain how to import the template file directly, not from the Community Template Gallery.

The server-side tag template is just a file with the '.tpl' extension.

Server-side tag templates can be used by importing them from the management screen of Google Tag Manager.

This guide assumes that you have already built a server-side container, and will explain how to import a server-side tag template.

If you haven't completed the build yet, follow Google's Server-side tagging documentation to build the server-side container.

Get tag template

Please get template.tpl in advance.

Add a new tag template

Go to the management page of Google Tag Manager and open your server side container workspace that was prepared in advance.

Select the Templates tab on the left and click the New button in the Tag Templates panel to open the template editor.

Tag Manager - New Tag Template

Import tag templates

When the template editor opens, select the menu in the upper right and click Import.

When the file selection dialog is displayed, select the template.tpl file that you prepared in advance.

Tag Manager - Import Tag Template

When the loading of the tag template is complete, you can preview the template and ensure that the display on the UI has been changed. Click the Save button on the upper right to save the template.

Tag Manager - Save Tag Template

If Conversion API is added to the tag template panel, the template has been installed correctly.

You can use this template for configuring server tags from now on.

Tag Manager - List Tag Template

Introduction to configuring server tags

Here is an example of actually installing a server tag into a container using a template and implementing server-side tagging.

After completing this step, you will be able to send events with a GA4 client through the Tag Manager web container and send conversion events to Conversion API with the server tags as shown below.

Conversion API GTM Overview

For the hierarchy of web pages where tags will be placed, we shall take the structure below for the sake of simplicity.

In this example, we want conversions to be measured only when conversion.html is accessed.

.
├── conversion.html
└── index.html

It is assumed to be accessed as https://{hostname}/conversion.html.

Web container configuration

As for the means of sending events to the server-side container with a GA4 Client, this time we will send them using Google Tag Manager.

Therefore, it's necessary to set up the GTM web container in advance. If you've already managed the measurement configuration of LINE Tag in the GTM web container, you can use it as is. If the tag for Google Tag Manager isn't still installed, please refer to the Quickstart guide to set it up.

Adding tags to the web container

The GA4 configuration tag was replaced with the Google tag in early September 2023. To send events to the server container, you need to set up the Google tag.

Open the web container workspace in Google Tag Manager, display the Tags list, and click the New button to create a new one. Select the Google Tag and add the server_container_url to the Configuration settings. Enter the URL of the pre-built server container as the value of that configuration parameter. With the above configuration, events can be sent to the server container by tags delivered by Google Tag Manager.

In order to pass the additional fields required by the server tag, it is necessary to set the items in Fields to Set. You also need to configure it properly when you intend to send built-in variables in Google Tag Manager and the data layer variables. For details on the additional fields expected by Conversion API server tag, see "About additional fields for server-side tag templates".

Web Container - GA4 Configuration

In this sample, the mapping between the variables created as data layer variables and the parameters to be additionally passed to server tag is registered as a combination of the field and value of "Fields to Set".

In addition, the web container's built-in page hostname and page path variables are also passed to the server container so that they can be used in the triggering condition of the server tag. These values are not defined as built-in variables. Instead, information relative to the requests to the server container such as request path and query string are defined as built-in variables. It seems that URL information about the original web page cannot be obtained (as of June 21, 2022).

Web Container - User-Defined Variables

Server-side container variable configuration

As preparation, define the variables that will be used in the server-side container.

Newly define Page Hostname and Page Path, which were explicitly set as Fields to Set in the web container configuration earlier, as User-Defined Variables.

Open the server side container workspace, select Variables from the left tab, and click New to define a variable.

Set the variable type to Event Data and set the key path to the value set on the web container side.

In this example, we set Page Hostname to "page_hostname" and Page Path to "page_pathvar", so we need to specify these values as key paths.

Server Side Container - Add User-Defined Variable

If you set the user-defined variables, they will look like this.

Server Side Container - List User-Defined Variables

Now, even on the server side container side, you can get the host name and path of the website when the tag fires on the client side.

Server tag configuration

Next, set up the server tag. The server-side tag template uses the "Conversion API" tag that was imported earlier.

Select Tags from the tab on the left side of the server-side container workspace, and click the New button from the tag panel.

Server Side Container - New Tag

When the tag addition menu is displayed, click Tag Configuration.

When the tag type selection menu is displayed, select Conversion API displayed in the custom item.

Server Side Container - Select Tag Template

After selecting a tag type, you will be able to enter the configuration items for the server-side tag template as shown below.

You can check the explanation of each item by hovering your cursor over the tool tip, but this guide also explains it. Please enter the item according to the explanation.

Server Side Container - Fill In Template Configuration
  1. Enter the LINE Tag ID you issued Conversion API with.
  2. Enter the access token for Conversion API issued on Business Manager.
  3. If you want to measure using LINE User IDs, enter the Channel ID of the Channel Provider that issues User IDs. For more information about Channels and User IDs, see "Channel" and "User IDs" on the LINE Developers site. please.
  4. Specify the event type you want to measure.
    1. PageView corresponds to LINE Tag base code.
    2. Conversion/Custom Conversion is equivalent to LINE Tag conversion code.
      1. If the event name to be sent is "Conversion", it will be sent as the default conversion event.
      2. Any other event name will be sent as a custom event.
  5. Specify a fixed event name. If you don't specify a fixed event name, the event name will be automatically set and sent from the event name in GA4. For example, when a page view occurs in GA4, the event name is set as " page_view". See Google Analytics - Event References for a description of this event. If you want explicit control over the event name, set a tag to always send the same event, or use the appropriate variables.
  6. Enable cookie measurement. By enabling this configuration, you can read first-party cookies, and also issue first-party cookies on the server container. It is necessary to set Custom domain configuration in advance, set the server container and the web page under the same domain, and prepare the server container to be regarded as first-party.

Configure triggering for tags

Next, set the conditions for triggering the configured server tag.

In this step, we'll set up the appropriate triggers to measure conversions when visiting conversion.html.

Get the URL information of the website where the tag of the web container fired, and set it as a triggering so that the tag fires when the conditions match.

Click Triggering"to display the triggering selection screen, and create a triggering from the button on the upper right.

Show Server Side Tag Details

In the triggering configuration, select Page View, set the server tag to fire only if the beginning of Page Hostname matches the expected hostname and Page Path equals "/conversion.html".

Set Triggering to Server Side Tag

The server tag configurations are now complete. Click Publish to publish your changes.

List Configured Server Tags

Debugging server-side containers

A method is provided to check whether events are actually sent to the server-side container.

Click the Preview button on the management page of the server side container to launch the debug page.

Push Button To Debug Server Side Container

You can check the following by accessing conversion.html and actually sending events from the web container.

  • Whether the server tag fired or not
  • Details of the HTTP request actually sent to Conversion API
  • Response from Conversion API
  • Contents of event data
  • Error logs
Debug Server Side Container

If a tag fires, it will be displayed as "Tags Fired".

If it doesn't fire, "Tags Not Fired" will be displayed. Check that the triggering configuration and the server container URL are correct.

Debug Server Side Container - Tag Fired

About additional fields for server-side tag templates

In addition to the data automatically collected when sending events to server-side tags in GA4, there is additional data that can be sent.

Additional data can be sent to the "corresponding fields of the Conversion API" by configuring additional values in the "Additional field" in the table below.

Additional field Corresponding fields of the Conversion API
x-line-deduplication_key event.deduplication_key
x-line-hashed_phone user.phone
x-line-hashed_email user.email
x-line-user_id user.line_uid
x-line-external_id user.external_id
x-line-ifa user.ifa
x-line-event-value custom.value
x-line-event-currency custom.currency

When sending events with GA4 from the Google Tag Manager web container, you can pass additional field as described in "Web container configuration".

In addition, for user_data.* data that can be used as Common event data, the values will be sent as the following corresponding fields if they are set for use. Unhashed values are automatically hashed and sent. See Google's documentation for configuration details.

Common event data Corresponding fields of the Conversion API
user_data.phone_number user.phone
user_data.email_address user.email

About deduplicationKey for event deduplication

deduplication_key is a required field used for event deduplication.

If nothing is specified in the additional configuration field x-line-deduplication_key, a random UUID will be generated and sent each time instead.

If an event is only sent once and limited to server-side tagging, deduplication isn't necessarily required.

However, if events are sent from multiple routes, events representing the same event would be sent multiple times.

For example, this applies when interoperating LINE Tag and server-side tagging.

Interoperability between Conversion API and LINE Tag in server-side tagging

By using Google Tag Manager, you can interoperate Conversion API and LINE Tags.

For example, if you use the Conversion API tag configured in this guide together with the LINE Tag configuration added as HTML tags, you can have both tags fire for the same event. However, in this case, it's essential to support event duplication elimination. Conversion measurement will be performed for each tag. To deduplicate this, you need to set the deduplication_key appropriately. Please check the Conversion API documentation for a detailed explanation of the deduplication_key itself.

Here is an example of how to set the same deduplication_key for the LINE Tag set in Google Tag Manager and the Conversion API Server Tag.

Set deduplication_key in data layer variable

One way to deduplicate is to set the deduplication_key as a data layer variable.

deduplication_key should be generated randomly to ensure uniqueness of the value, and the same value should be received by both LINE Tag and Conversion API.

A deduplication_key is generated by a JavaScript function as follows, and the result is set in the data layer variable.


<script>
    window.dataLayer = window.dataLayer || [];

    function getDeduplicationKey() {
        return Date.now() + '_' + Math.floor((Math.random() * 10 ** 9));
    }

    dataLayer.push({
        'x-line-deduplication_key': getDeduplicationKey()
    });
</script>

This data layer variable is set as deduplicationKey in the LINE tag in web containers and passed as x-line-deduplication_key in server-side containers. In this way, deduplication is possible by passing the same deduplication_key over separate routes.

Notes

  • When using the server-side tag template provided by our company, the privacy policy and terms of use for using the Conversion API are also applied.
  • We do not guarantee that the server-side tag templates we provide at this time will work correctly.
  • Please contact the service provider for any inquiries regarding services not provided by our company, such as Google Tag Manager, Google Cloud Platform, and Google Analytics.
  • We cannot compensate for any disadvantages caused by modifying the server-side tag template provided by our company on your own.

Terms of use

Our Conversion API terms of use will apply to your use of the Conversion API. Please refer to the document for details.

LINE Conversion API v1

Send Conversion Event

Conversion API allows you to send additional information about conversion events in addition to the information normally sent by LINE Tag.

The sent events are used for conversion measurement, audience accumulation, reporting, and delivery optimization on LINE.

path Parameters
line_tag_id
required
string

Specify the LINE Tag ID you want to use for conversion measurement with Conversion API.

header Parameters
X-Line-TagAccessToken
required
string

Specify the access token for Conversion API issued by Business Manager. The access token for Conversion API must be being associated with the LINE Tag ID specified by the line_tag_id parameter.

X-Line-ChannelID
string

Specify the channel ID. Use the channel ID of the channel that issued the LINE User ID specified by user.line_uid. This field is required for user matching using LINE User IDs.

Request Body schema: application/json
Array
object (WebObj)

An object that contains a set of information to represent an occurred event if source_type is specified to web.

required
object (EventObj)

An object that contains a set of information to represent an occurred event.

required
object (UserObj)

An object that contains a set of information to represent the user who raised the event.

object (CustomObj)

An object that contains a set of information for the standard event. It will be used in optimization and reporting.

Responses

Request samples

Content type
application/json
[
  • {
    }
]