Remarketing Samples

The code samples below provide examples of common remarketing functions using the AdWords API. Client Library.

Add audience

' Copyright 2017, Google Inc. All Rights Reserved.
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201710

Namespace Google.Api.Ads.AdWords.Examples.VB.v201710
  ''' <summary>
  ''' This code example illustrates how to create a user list a.k.a. audience.
  ''' </summary>
  Public Class AddAudience
    Inherits ExampleBase
    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      Dim codeExample As New AddAudience
      Console.WriteLine(codeExample.Description)
      Try
        codeExample.Run(New AdWordsUser)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example illustrates how to create a user list a.k.a. audience."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    Public Sub Run(ByVal user As AdWordsUser)
      Using userListService As AdwordsUserListService = CType(user.GetService(
          AdWordsService.v201710.AdwordsUserListService), AdwordsUserListService)

        Using conversionTrackerService As ConversionTrackerService = CType(user.GetService(
          AdWordsService.v201710.ConversionTrackerService),
            ConversionTrackerService)

          Dim userList As New BasicUserList

          userList.name = ("Mars cruise customers #" & ExampleUtilities.GetRandomString)
          userList.description = "A list of mars cruise customers in the last year."
          userList.status = UserListMembershipStatus.OPEN
          userList.membershipLifeSpan = 365

          Dim conversionType As New UserListConversionType
          conversionType.name = userList.name
          userList.conversionTypes = New UserListConversionType() {conversionType}

          ' Optional: Set the user list status.
          userList.status = UserListMembershipStatus.OPEN

          ' Create the operation.
          Dim operation As New UserListOperation
          operation.operand = userList
          operation.operator = [Operator].ADD

          Try
            ' Add the user list.
            Dim retval As UserListReturnValue = userListService.mutate(
                New UserListOperation() {operation})

            Dim userLists As UserList() = Nothing
            If (Not retval Is Nothing) AndAlso (Not retval.value Is Nothing) Then
              userLists = retval.value
              ' Get all conversion snippets.
              Dim conversionIds As New List(Of String)
              For Each newUserList As BasicUserList In userLists
                If (Not newUserList.conversionTypes Is Nothing) Then
                  For Each newConversionType As UserListConversionType In
                      newUserList.conversionTypes
                    conversionIds.Add(newConversionType.id.ToString)
                  Next
                End If
              Next

              Dim conversionsMap As New Dictionary(Of Long, ConversionTracker)

              If (conversionIds.Count > 0) Then
                ' Create the selector.
                Dim selector As New Selector
                selector.fields = New String() {ConversionTracker.Fields.Id}

                selector.predicates = New Predicate() {
                  Predicate.In(ConversionTracker.Fields.Id, conversionIds)
                }

                ' Get all conversion trackers.
                Dim page As ConversionTrackerPage = conversionTrackerService.get(selector)

                If (Not page Is Nothing) AndAlso (Not page.entries Is Nothing) Then
                  For Each tracker As ConversionTracker In page.entries
                    conversionsMap.Item(tracker.id) = tracker
                  Next
                End If
              End If

              ' Display the results.
              For Each newUserList As BasicUserList In userLists
                Console.WriteLine("User list with name '{0}' and id '{1}' was added.",
                    newUserList.name, newUserList.id)

                ' Display user list associated conversion code snippets.
                If (Not newUserList.conversionTypes Is Nothing) Then
                  For Each newConversionType As UserListConversionType In
                      newUserList.conversionTypes
                    Dim conversionTracker As AdWordsConversionTracker =
                        DirectCast(conversionsMap.Item(newConversionType.id),
                            AdWordsConversionTracker)
                    Console.WriteLine("Conversion type code snippet associated to the list:\n{0}",
                        conversionTracker.snippet)
                  Next
                End If
              Next
            Else
              Console.WriteLine("No user lists (a.k.a. audiences) were added.")
            End If
          Catch e As Exception
            Throw New System.ApplicationException("Failed to add user lists (a.k.a. " +
                "audiences).", e)
          End Try
        End Using
      End Using
    End Sub
  End Class
End Namespace

Add conversion trackers

' Copyright 2017, Google Inc. All Rights Reserved.
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201710

Namespace Google.Api.Ads.AdWords.Examples.VB.v201710
  ''' <summary>
  ''' This code example adds an AdWords conversion tracker and an upload conversion tracker.
  ''' </summary>
  Public Class AddConversionTrackers
    Inherits ExampleBase
    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      Dim codeExample As New AddConversionTrackers
      Console.WriteLine(codeExample.Description)
      Try
        codeExample.Run(New AdWordsUser)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    '''
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example adds an AdWords conversion tracker and an upload conversion " &
            "tracker."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    Public Sub Run(ByVal user As AdWordsUser)
      ' Get the ConversionTrackerService.
      Using conversionTrackerService As ConversionTrackerService = CType(user.GetService(
          AdWordsService.v201710.ConversionTrackerService),
              ConversionTrackerService)

        Dim conversionTrackers As New List(Of ConversionTracker)

        ' Create an Adwords conversion tracker.
        Dim adWordsConversionTracker As New AdWordsConversionTracker()
        adWordsConversionTracker.name = "Earth to Mars Cruises Conversion #" &
            ExampleUtilities.GetRandomString()
        adWordsConversionTracker.category = ConversionTrackerCategory.DEFAULT

        ' Set optional fields.
        adWordsConversionTracker.status = ConversionTrackerStatus.ENABLED
        adWordsConversionTracker.viewthroughLookbackWindow = 15
        adWordsConversionTracker.defaultRevenueValue = 23.41
        adWordsConversionTracker.alwaysUseDefaultRevenueValue = True
        conversionTrackers.Add(adWordsConversionTracker)

        ' Create an upload conversion for offline conversion imports.
        Dim uploadConversion As New UploadConversion()
        ' Set an appropriate category. This field is optional, and will be set to
        ' DEFAULT if not mentioned.
        uploadConversion.category = ConversionTrackerCategory.LEAD
        uploadConversion.name = "Upload Conversion #" + ExampleUtilities.GetRandomString()
        uploadConversion.viewthroughLookbackWindow = 30
        uploadConversion.ctcLookbackWindow = 90

        ' Optional: Set the default currency code to use for conversions
        ' that do not specify a conversion currency. This must be an ISO 4217
        ' 3-character currency code such as "EUR" or "USD".
        ' If this field is not set on this UploadConversion, AdWords will use
        ' the account's currency.
        uploadConversion.defaultRevenueCurrencyCode = "EUR"

        ' Optional: Set the default revenue value to use for conversions
        ' that do not specify a conversion value. Note that this value
        ' should NOT be in micros.
        uploadConversion.defaultRevenueValue = 2.5

        ' Optional: To upload fractional conversion credits, mark the upload conversion
        ' as externally attributed. See
        ' https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
        ' to learn more about importing externally attributed conversions.

        ' uploadConversion.isExternallyAttributed = True

        conversionTrackers.Add(uploadConversion)

        Try
          ' Create operations.
          Dim operations As New List(Of ConversionTrackerOperation)
          For Each conversionTracker As ConversionTracker In conversionTrackers
            Dim operation As New ConversionTrackerOperation()
            operation.operator = [Operator].ADD
            operation.operand = conversionTracker
            operations.Add(operation)
          Next

          ' Add conversion tracker.
          Dim retval As ConversionTrackerReturnValue = conversionTrackerService.mutate(
              operations.ToArray())

          ' Display the results.
          If (Not retval Is Nothing) AndAlso (Not retval.value Is Nothing) AndAlso
              retval.value.Length > 0 Then
            For Each conversionTracker As ConversionTracker In retval.value
              If TypeOf conversionTracker Is AdWordsConversionTracker Then
                Dim newAdWordsConversionTracker As AdWordsConversionTracker =
                    CType(conversionTracker, AdWordsConversionTracker)
                Console.WriteLine("Conversion with ID {0}, name '{1}', status '{2}', category " &
                    "'{3}' and snippet '{4}' was added.",
                    newAdWordsConversionTracker.id, newAdWordsConversionTracker.name,
                    newAdWordsConversionTracker.status, newAdWordsConversionTracker.category,
                    newAdWordsConversionTracker.snippet)
              Else
                Console.WriteLine("Conversion with ID {0}, name '{1}', status '{2}' and " &
                    "category '{3}' was added.", conversionTracker.id, conversionTracker.name,
                    conversionTracker.status, conversionTracker.category)
              End If
            Next
          Else
            Console.WriteLine("No conversion trackers were added.")
          End If
        Catch e As Exception
          Throw New System.ApplicationException("Failed to add conversion trackers.", e)
        End Try
      End Using
    End Sub
  End Class
End Namespace

Add rule-based user list

' Copyright 2017, Google Inc. All Rights Reserved.
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201710

Namespace Google.Api.Ads.AdWords.Examples.VB.v201710
  ''' <summary>
  ''' This code example adds two rule-based remarketing user lists: one with no
  ''' site visit date restrictions, and another that will only include users
  ''' who visit your site in the next six months.  See
  ''' https://developers.google.com/adwords/api/docs/guides/rule-based-remarketing
  ''' to learn more about rule based remarketing.
  ''' </summary>
  Public Class AddRuleBasedRemarketingList
    Inherits ExampleBase
    Private Const DATE_FORMAT_STRING As String = "yyyyMMdd"

    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      Dim codeExample As New AddRuleBasedRemarketingList
      Console.WriteLine(codeExample.Description)
      Try
        codeExample.Run(New AdWordsUser)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example adds two rule-based remarketing user lists: one with no " &
            "site visit date restrictions, and another that will only include users who " &
            "visit your site in the next six months. See " &
            "https://developers.google.com/adwords/api/docs/guides/rule-based-remarketing to " &
            "learn more about rule based remarketing."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    Public Sub Run(ByVal user As AdWordsUser)
      Using userListService As AdwordsUserListService = CType(user.GetService(
          AdWordsService.v201710.AdwordsUserListService), AdwordsUserListService)

        ' First rule item group - users who visited the checkout page and had
        ' more than one item in their shopping cart.
        Dim checkoutStringRuleItem As New StringRuleItem()
        checkoutStringRuleItem.key = New StringKey()
        checkoutStringRuleItem.key.name = "ecomm_pagetype"
        checkoutStringRuleItem.op = StringRuleItemStringOperator.EQUALS
        checkoutStringRuleItem.value = "checkout"

        Dim checkoutRuleItem As New RuleItem()
        checkoutRuleItem.Item = checkoutStringRuleItem

        Dim cartSizeNumberRuleItem As New NumberRuleItem()
        cartSizeNumberRuleItem.key = New NumberKey()
        cartSizeNumberRuleItem.key.name = "cartsize"
        cartSizeNumberRuleItem.op = NumberRuleItemNumberOperator.GREATER_THAN
        cartSizeNumberRuleItem.value = 1

        Dim cartSizeRuleItem As New RuleItem()
        cartSizeRuleItem.Item = cartSizeNumberRuleItem

        ' Combine the two rule items into a RuleItemGroup so AdWords will AND
        ' their(rules) together.
        Dim checkoutMultipleItemGroup As New RuleItemGroup()
        checkoutMultipleItemGroup.items = New RuleItem() {checkoutRuleItem, cartSizeRuleItem}

        ' Second rule item group - users who check out within the next 3 months.
        Dim startDateDateRuleItem As New DateRuleItem()
        startDateDateRuleItem.key = New DateKey()
        startDateDateRuleItem.key.name = "checkoutdate"
        startDateDateRuleItem.op = DateRuleItemDateOperator.AFTER
        startDateDateRuleItem.value = DateTime.Now.ToString(DATE_FORMAT_STRING)
        Dim startDateRuleItem As New RuleItem()
        startDateRuleItem.Item = startDateDateRuleItem

        Dim endDateDateRuleItem As New DateRuleItem()
        endDateDateRuleItem.key = New DateKey()
        endDateDateRuleItem.key.name = "checkoutdate"
        endDateDateRuleItem.op = DateRuleItemDateOperator.BEFORE
        endDateDateRuleItem.value = DateTime.Now.AddMonths(3).ToString(DATE_FORMAT_STRING)
        Dim endDateRuleItem As New RuleItem()
        endDateRuleItem.Item = endDateDateRuleItem

        ' Combine the date rule items into a RuleItemGroup.
        Dim checkedOutNextThreeMonthsItemGroup As New RuleItemGroup()
        checkedOutNextThreeMonthsItemGroup.items =
            New RuleItem() {startDateRuleItem, endDateRuleItem}

        ' Combine the rule item groups into a Rule so AdWords knows how to apply the rules.
        Dim rule As New Rule()
        rule.groups = New RuleItemGroup() {
          checkoutMultipleItemGroup, checkedOutNextThreeMonthsItemGroup
        }

        ' ExpressionRuleUserLists can use either CNF Or DNF For matching. CNF means
        ' 'at least one item in each rule item group must match', and DNF means 'at
        ' least one entire rule item group must match'.
        ' DateSpecificRuleUserList only supports DNF. You can also omit the rule
        ' type altogether To Default To DNF.
        rule.ruleType = UserListRuleTypeEnumsEnum.DNF


        ' Third And fourth rule item groups.
        ' Visitors of a page who visited another page. See
        ' https//developers.google.com/adwords/api/docs/reference/latest/AdwordsUserListService.StringKey
        ' for more details.
        Dim urlStringKey As New StringKey()
        urlStringKey.name = "url__"

        Dim site1StringRuleItem As New StringRuleItem()
        site1StringRuleItem.key = urlStringKey
        site1StringRuleItem.op = StringRuleItemStringOperator.EQUALS
        site1StringRuleItem.value = "example.com/example1"
        Dim site1RuleItem As New RuleItem()
        site1RuleItem.Item = site1StringRuleItem

        Dim site2StringRuleItem As New StringRuleItem()
        site2StringRuleItem.key = urlStringKey
        site2StringRuleItem.op = StringRuleItemStringOperator.EQUALS
        site2StringRuleItem.value = "example.com/example2"
        Dim site2RuleItem As New RuleItem()
        site2RuleItem.Item = site2StringRuleItem

        ' Create two RuleItemGroups to show that a visitor browsed two sites.
        Dim site1RuleItemGroup As New RuleItemGroup()
        site1RuleItemGroup.items = New RuleItem() {site1RuleItem}
        Dim site2RuleItemGroup As New RuleItemGroup()
        site2RuleItemGroup.items = New RuleItem() {site2RuleItem}

        ' Create two rules to show that a visitor browsed two sites.
        Dim userVisitedSite1Rule As New Rule()
        userVisitedSite1Rule.groups = New RuleItemGroup() {site1RuleItemGroup}

        Dim userVisitedSite2Rule As New Rule()
        userVisitedSite2Rule.groups = New RuleItemGroup() {site2RuleItemGroup}

        ' Create the user list with no restrictions on site visit date.
        Dim expressionUserList As New ExpressionRuleUserList()
        Dim creationTimeString As String = DateTime.Now.ToString("yyyyMMdd_HHmmss")

        expressionUserList.name = "Expression based user list created at " + creationTimeString
        expressionUserList.description = "Users who checked out in three month window OR " &
            "visited the checkout page with more than one item in their cart."
        expressionUserList.rule = rule

        ' Optional: Set the prepopulationStatus to REQUESTED to include past users
        ' in the user list.
        expressionUserList.prepopulationStatus = RuleBasedUserListPrepopulationStatus.REQUESTED

        ' Create the user list restricted to users who visit your site within
        ' the next six months.
        Dim startDate As DateTime = DateTime.Now
        Dim endDate As DateTime = startDate.AddMonths(6)

        Dim dateUserList As New DateSpecificRuleUserList()
        dateUserList.name = "Date rule user list created at " + creationTimeString
        dateUserList.description = String.Format("Users who visited the site between {0} and " &
            "{1} and checked out in three month window OR visited the checkout page " &
            "with more than one item in their cart.", startDate.ToString(DATE_FORMAT_STRING),
            endDate.ToString(DATE_FORMAT_STRING))
        dateUserList.rule = rule

        ' Set the start and end dates of the user list.
        dateUserList.startDate = startDate.ToString(DATE_FORMAT_STRING)
        dateUserList.endDate = endDate.ToString(DATE_FORMAT_STRING)

        ' Create the user list where "Visitors of a page who did visit another page".
        ' To create a user list where "Visitors of a page who did not visit another
        ' page", change the ruleOperator from And to AND_NOT.
        Dim CombinedRuleUserList As New CombinedRuleUserList()
        CombinedRuleUserList.name = "Combined rule user list created at " + creationTimeString
        CombinedRuleUserList.description = "Users who visited two sites."
        CombinedRuleUserList.leftOperand = userVisitedSite1Rule
        CombinedRuleUserList.rightOperand = userVisitedSite2Rule
        CombinedRuleUserList.ruleOperator = CombinedRuleUserListRuleOperator.AND

        ' Create operations to add the user lists.
        Dim operations As New List(Of UserListOperation)
        For Each userList As UserList In New UserList() {expressionUserList, dateUserList,
            CombinedRuleUserList}
          Dim operation As New UserListOperation()
          operation.operand = userList
          operation.operator = [Operator].ADD
          operations.Add(operation)
        Next

        Try
          ' Submit the operations.
          Dim result As UserListReturnValue = userListService.mutate(operations.ToArray())

          ' Display the results.
          For Each userListResult As UserList In result.value
            Console.WriteLine("User list added with ID {0}, name '{1}', status '{2}', " +
                "list type '{3}', accountUserListStatus '{4}', description '{5}'.",
                userListResult.id,
                userListResult.name,
                userListResult.status,
                userListResult.listType,
                userListResult.accountUserListStatus,
                userListResult.description)
          Next
        Catch e As Exception
          Throw New System.ApplicationException("Failed to add rule based user lists.", e)
        End Try
      End Using
    End Sub
  End Class
End Namespace

Upload offline conversions

' Copyright 2017, Google Inc. All Rights Reserved.
'
' Licensed under the Apache License, Version 2.0 (the "License")
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http:'www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201710

Namespace Google.Api.Ads.AdWords.Examples.VB.v201710
  ''' <summary>
  ''' This code example imports offline conversion values for specific clicks to
  ''' your account. To get Google Click ID for a click, run
  ''' CLICK_PERFORMANCE_REPORT. To set up a conversion tracker, run the
  ''' AddConversionTrackers.vb example.
  ''' </summary>
  Public Class UploadOfflineConversions
    Inherits ExampleBase

    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      Dim conversionName As String = "INSERT_CONVERSION_NAME_HERE"
      ' GCLID needs to be newer than 30 days.
      Dim gClId As String = "INSERT_GOOGLE_CLICK_ID_HERE"
      '  The conversion time should be higher than the click time.
      Dim conversionTime As String = "INSERT_CONVERSION_TIME_HERE"
      Dim conversionValue As Double = Double.Parse("INSERT_CONVERSION_VALUE_HERE")

      Dim codeExample As New UploadOfflineConversions
      Console.WriteLine(codeExample.Description)
      Try
        codeExample.Run(New AdWordsUser, conversionName, gClId, conversionTime, conversionValue)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example imports offline conversion values for specific clicks to " &
            "your account. To get Google Click ID for a click, run CLICK_PERFORMANCE_REPORT. " &
            "To set up a conversion tracker, run the AddConversionTrackers.vb example."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    ''' <param name="conversionName">The name of the upload conversion to be
    ''' created.</param>
    ''' <param name="gClid">The Google Click ID of the click for which offline
    ''' conversions are uploaded.</param>
    ''' <param name="conversionValue">The conversion value to be uploaded.
    ''' </param>
    ''' <param name="conversionTime">The conversion time, in yyyymmdd hhmmss
    ''' format.</param>
    Public Sub Run(ByVal user As AdWordsUser, ByVal conversionName As String,
        ByVal gClid As String, ByVal conversionTime As String, ByVal conversionValue As Double)
      Using offlineConversionFeedService As OfflineConversionFeedService = CType(user.GetService(
          AdWordsService.v201710.OfflineConversionFeedService),
              OfflineConversionFeedService)

        Try
          ' Associate offline conversions with the existing named conversion tracker. If
          ' this tracker was newly created, it may be a few hours before it can accept
          ' conversions.
          Dim feed As New OfflineConversionFeed()
          feed.conversionName = conversionName
          feed.conversionTime = conversionTime
          feed.conversionValue = conversionValue
          feed.googleClickId = gClid

          ' Optional: To upload fractional conversion credits, set the external attribution model
          ' and credit. To use this feature, your conversion tracker should be marked as externally
          ' attributed. See
          ' https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
          ' to learn more about importing externally attributed conversions.

          ' feed.externalAttributionModel = "Linear"
          ' feed.externalAttributionCredit = 0.3

          Dim offlineConversionOperation As New OfflineConversionFeedOperation()
          offlineConversionOperation.operator = [Operator].ADD
          offlineConversionOperation.operand = feed

          Dim offlineConversionRetval As OfflineConversionFeedReturnValue =
            offlineConversionFeedService.mutate(
                New OfflineConversionFeedOperation() {offlineConversionOperation})

          Dim newFeed As OfflineConversionFeed = offlineConversionRetval.value(0)

          Console.WriteLine("Uploaded offline conversion value of {0} for Google Click ID = " &
              "'{1}' to '{2}'.", newFeed.conversionValue, newFeed.googleClickId,
              newFeed.conversionName)
        Catch e As Exception
          Throw New System.ApplicationException("Failed to upload offline conversions.", e)
        End Try
      End Using
    End Sub
  End Class
End Namespace

Upload offline call conversions

' Copyright 2017, Google Inc. All Rights Reserved.
'
' Licensed under the Apache License, Version 2.0 (the "License")
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http:'www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201710

Namespace Google.Api.Ads.AdWords.Examples.VB.v201710
  ''' <summary>
  ''' This code example imports offline call conversion values for calls related
  ''' to the ads in your account.
  ''' </summary>
  Public Class UploadOfflineCallConversions
    Inherits ExampleBase

    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      Dim conversionName As String = "INSERT_CONVERSION_NAME_HERE"

      ' For times use the format yyyyMMdd HHmmss tz. For more details on formats, see:
      ' https://developers.google.com/adwords/api/docs/appendix/codes-formats#date-and-time-formats
      ' For time zones, see:
      ' https://developers.google.com/adwords/api/docs/appendix/codes-formats#timezone-ids

      '  The conversion time should be after the call start time.
      Dim conversionTime As String = "INSERT_CONVERSION_TIME_HERE"
      Dim callStartTime As String = "INSERT_CALL_START_TIME_HERE"

      Dim conversionValue As Double = Double.Parse("INSERT_CONVERSION_VALUE_HERE")
      Dim callerId As String = "INSERT_CALLER_ID_HERE"

      Dim codeExample As New UploadOfflineCallConversions
      Console.WriteLine(codeExample.Description)
      Try
        codeExample.Run(New AdWordsUser, conversionName, callStartTime, callerId,
                        conversionTime, conversionValue)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example imports offline call conversion values for calls related " &
            " to the ads in your account."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    ''' <param name="conversionName">The name of the call conversion to be updated.</param>
    ''' <param name="callStartTime">The call start time.</param>
    ''' <param name="conversionValue">The conversion value to be uploaded.</param>
    ''' <param name="callerId">The caller ID to be uploaded.</param>
    ''' <param name="conversionTime">The conversion time, in yyyymmdd hhmmss format.</param>
    Public Sub Run(ByVal user As AdWordsUser, ByVal conversionName As String,
        ByVal callStartTime As String, ByVal callerId As String,
        ByVal conversionTime As String, ByVal conversionValue As Double)
      Using offlineCallConversionFeedService As OfflineCallConversionFeedService =
          CType(user.GetService(AdWordsService.v201710.OfflineCallConversionFeedService),
              OfflineCallConversionFeedService)

        ' Associate offline call conversions with the existing named conversion tracker. If this
        ' tracker was newly created, it may be a few hours before it can accept conversions.
        Dim feed As New OfflineCallConversionFeed()
        feed.callerId = callerId
        feed.callStartTime = callStartTime
        feed.conversionName = conversionName
        feed.conversionTime = conversionTime
        feed.conversionValue = conversionValue

        Dim offlineCallConversionOperation As New OfflineCallConversionFeedOperation()
        offlineCallConversionOperation.operator = [Operator].ADD
        offlineCallConversionOperation.operand = feed

        Try
          ' This example uploads only one call conversion, but you can upload
          ' multiple call conversions by passing additional operations.
          Dim offlineCallConversionReturnValue As OfflineCallConversionFeedReturnValue =
            offlineCallConversionFeedService.mutate(
                New OfflineCallConversionFeedOperation() {offlineCallConversionOperation})

          ' Display results.
          For Each feedResult As OfflineCallConversionFeed In
              offlineCallConversionReturnValue.value
            Console.WriteLine("Uploaded offline call conversion value of {0} for caller ID '{1}'.",
                feedResult.conversionValue, feedResult.callerId)
          Next
        Catch e As Exception
          Throw New System.ApplicationException("Failed to upload offline call conversions.", e)
        End Try
      End Using
    End Sub
  End Class
End Namespace

Upload offline data


' Copyright 2017, Google Inc. All Rights Reserved.
'
' Licensed under the Apache License, Version 2.0 (the "License")
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
'     http:'www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.

Imports System.Text
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201710
Imports Org.BouncyCastle.Crypto.Digests

Namespace Google.Api.Ads.AdWords.Examples.VB.v201710

  ''' <summary>
  ''' This code example shows how to upload offline data for store sales transactions.
  ''' </summary>
  Public Class UploadOfflineData
    Inherits ExampleBase

    Private Shared ReadOnly digest As New Sha256Digest()

    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      ' The external upload ID can be any number that you use to keep track of your uploads.
      Dim externalUploadId As Long = Long.Parse("INSERT_EXTERNAL_UPLOAD_ID")

      ' Insert the conversion type name that you'd like to attribute this upload to.
      Dim conversionName As String = "INSERT_CONVERSION_NAME"

      ' Insert email addresses below for creating user identifiers.
      Dim emailAddresses As String() = {"EMAIL_ADDRESS_1", "EMAIL_ADDRESS_2"}

      Dim codeExample As New UploadOfflineData
      Console.WriteLine(codeExample.Description)
      Try
        codeExample.Run(New AdWordsUser, conversionName, externalUploadId, emailAddresses)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example shows how to upload offline data for store sales transactions."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    ''' <param name="conversionName">The conversion type name that you'd like to attribute this
    ''' upload to.</param>
    ''' <param name="externalUploadId">The external upload ID can be any number that you use to
    ''' keep track of your uploads.</param>
    ''' <param name="emailAddresses">The email addresses for creating user identifiers.</param>
    Public Sub Run(ByVal user As AdWordsUser, ByVal conversionName As String,
        ByVal externalUploadId As Long, ByVal emailAddresses As String())
      Using offlineDataUploadService As OfflineDataUploadService = CType(user.GetService(
          AdWordsService.v201710.OfflineDataUploadService),
              OfflineDataUploadService)

        ' Create the first offline data row for upload.
        ' This transaction occurred 7 days ago with amount of 200 USD.
        Dim transactionTime1 As New DateTime()
        transactionTime1.AddDays(-7)
        Dim transactionAmount1 As Long = 200000000
        Dim transactionCurrencyCode1 As String = "USD"
        Dim userIdentifierList1 As UserIdentifier() = {
          CreateUserIdentifier(OfflineDataUploadUserIdentifierType.HASHED_EMAIL,
              emailAddresses(0)),
          CreateUserIdentifier(OfflineDataUploadUserIdentifierType.STATE, "New York")
        }

        Dim offlineData1 As OfflineData = CreateOfflineDataRow(transactionTime1,
            transactionAmount1, transactionCurrencyCode1, conversionName, userIdentifierList1)

        ' Create the second offline data row for upload.
        ' This transaction occurred 14 days ago with amount of 450 EUR.
        Dim transactionTime2 As New DateTime()
        transactionTime2.AddDays(-14)
        Dim transactionAmount2 As Long = 450000000
        Dim transactionCurrencyCode2 As String = "EUR"
        Dim userIdentifierList2 As UserIdentifier() = {
          CreateUserIdentifier(OfflineDataUploadUserIdentifierType.HASHED_EMAIL,
              emailAddresses(1)),
          CreateUserIdentifier(OfflineDataUploadUserIdentifierType.STATE, "California")
        }
        Dim offlineData2 As OfflineData = CreateOfflineDataRow(transactionTime2,
            transactionAmount2, transactionCurrencyCode2, conversionName, userIdentifierList2)

        ' Create offline data upload object.
        Dim offlineDataUpload As New OfflineDataUpload()
        offlineDataUpload.externalUploadId = externalUploadId
        offlineDataUpload.offlineDataList = New OfflineData() {offlineData1, offlineData2}

        ' Optional: You can set the type of this upload.
        ' offlineDataUpload.uploadType = OfflineDataUploadType.STORE_SALES_UPLOAD_FIRST_PARTY

        ' Create an offline data upload operation.
        Dim offlineDataUploadOperation As New OfflineDataUploadOperation()
        offlineDataUploadOperation.operator = [Operator].ADD
        offlineDataUploadOperation.operand = offlineDataUpload

        Try
          ' Upload offline data to the server.
          Dim result As OfflineDataUploadReturnValue = offlineDataUploadService.mutate(
            New OfflineDataUploadOperation() {offlineDataUploadOperation})
          offlineDataUpload = result.value(0)

          ' Print the upload ID and status.
          Console.WriteLine("Uploaded offline data with external upload ID {0}, " +
              "and upload status {1}.", offlineDataUpload.externalUploadId,
              offlineDataUpload.uploadStatus)

          ' Print any partial data errors from the response. The order of the partial
          ' data errors list Is the same as the uploaded offline data list in the
          ' request.
          If Not offlineDataUpload.partialDataErrors Is Nothing Then
            For i As Integer = 0 To offlineDataUpload.partialDataErrors.Length
              Dim partialDataError As ApiError = offlineDataUpload.partialDataErrors(i)
              Console.WriteLine("Found a partial error for offline data {0} with error " +
                  "string: {1}.", i + 1, partialDataError.errorString)
            Next
          End If
        Catch e As Exception
          Throw New System.ApplicationException("Failed to upload offline conversions.", e)
        End Try
      End Using
    End Sub

    ''' <summary>
    ''' Creates the offline data row from the specified transaction time, transaction micro amount,
    ''' transaction currency, conversion name And user identifier list.
    ''' </summary>
    ''' <param name="transactionTime">The transaction time.</param>
    ''' <param name="transactionMicroAmount">The transaction micro amount.</param>
    ''' <param name="transactionCurrency">The transaction currency.</param>
    ''' <param name="conversionName">Name of the conversion.</param>
    ''' <param name="userIdentifierList">The user identifier list.</param>
    ''' <returns>The offline data.</returns>
    Function CreateOfflineDataRow(ByVal transactionTime As DateTime,
        ByVal transactionMicroAmount As Long, ByVal transactionCurrency As String,
        ByVal conversionName As String, ByVal userIdentifierList As UserIdentifier()) _
        As OfflineData
      Dim storeSalesTransaction As New StoreSalesTransaction()

      ' For times use the format yyyyMMdd HHmmss [tz].
      ' For details, see
      ' https://developers.google.com/adwords/api/docs/appendix/codes-formats#date-And-time-formats
      storeSalesTransaction.transactionTime = transactionTime.ToString("Ymd His")
      storeSalesTransaction.conversionName = conversionName
      storeSalesTransaction.userIdentifiers = userIdentifierList

      Dim money As New Money()
      money.microAmount = transactionMicroAmount
      Dim moneyWithCurrency As New MoneyWithCurrency()
      moneyWithCurrency.money = money
      moneyWithCurrency.currencyCode = transactionCurrency
      storeSalesTransaction.transactionAmount = moneyWithCurrency

      Dim offlineData As New OfflineData()
      offlineData.Item = storeSalesTransaction

      Return offlineData
    End Function

    ''' <summary>
    ''' Hash a string value using SHA-256 hashing algorithm.
    ''' </summary>
    ''' <param name="digest">Provides the algorithm for SHA-256.</param>
    ''' <param name="value">The string value (e.g. an email address) to hash.</param>
    ''' <returns>The hashed value.</returns>
    Private Shared Function ToSha256String(ByVal digest As GeneralDigest,
        ByVal value As String) As String
      Dim data As Byte() = Encoding.UTF8.GetBytes(value)
      Dim digestBytes(digest.GetDigestSize()) As Byte
      digest.BlockUpdate(data, 0, data.Length)
      digest.DoFinal(digestBytes, 0)

      ' Convert the byte array into an unhyphenated hexadecimal string.
      Return BitConverter.ToString(digestBytes).Replace("-", String.Empty)
    End Function

    ''' <summary>
    ''' Creates the user identifier.
    ''' </summary>
    ''' <param name="type">The user identifier type.</param>
    ''' <param name="value">The user identifier value.</param>
    ''' <returns></returns>
    Function CreateUserIdentifier(ByVal type As OfflineDataUploadUserIdentifierType,
        ByVal value As String) As UserIdentifier
      ' If the user identifier type Is a hashed type, also call hash function
      ' on the value.
      If type.ToString().StartsWith("HASHED_") Then
        value = ToSha256String(digest, ToNormalizedValue(value))
      End If
      Dim userIdentifier As New UserIdentifier()
      userIdentifier.userIdentifierType = type
      userIdentifier.value = value

      Return userIdentifier
    End Function

    ''' <summary>
    ''' Removes leading And trailing whitespace And converts all characters to
    ''' lower case.
    ''' </summary>
    ''' <param name="value">The value to normalize.</param>
    ''' <returns>The normalized value.</returns>
    Private Shared Function ToNormalizedValue(ByVal value As String) As String
      Return value.Trim().ToLower()
    End Function
  End Class

End Namespace

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.