반복 잠재고객 목록

이 문서에서는 Google 애널리틱스 Data API v1의 고급 기능인 반복 잠재고객 목록에 대해 설명합니다. 잠재고객 목록 내보내기 기능에 대한 소개는 잠재고객 내보내기 기본사항 가이드를 참고하세요.

반복 잠재고객 목록은 잠재고객 멤버십이 변경될 때마다 매일 잠재고객 목록을 생성하여 최신 데이터를 사용할 수 있도록 합니다.

일반 (비반복) 잠재고객 목록은 목록이 생성될 때 잠재고객에 있는 사용자의 정적 목록입니다.

매일 새 잠재고객 목록 만들기

하루의 잠재고객 데이터를 처리하고 멤버십을 업데이트하는 데 걸리는 시간은 다양합니다. 잠재고객 목록 데이터가 24시간 이내에 업데이트된다고 보장할 수 없습니다.

예를 들어 매일 같은 시간에 잠재고객 목록을 요청하더라도 어떤 날에는 잠재고객 목록이 전날과 동일하고 어떤 날에는 잠재고객 목록이 달라져서 하루 동안의 추가 회원 변경사항이 포함됩니다.

매일 새 잠재고객 목록 만들기

잠재고객 목록은 가장 최근의 멤버십 변경 전날의 이벤트 데이터를 기반으로 합니다. 일일 회원 업데이트가 발생하기 전에 잠재고객 목록을 만들면 2일 전의 데이터가 사용됩니다. 일일 멤버십 업데이트가 발생한 후에 잠재고객 목록을 만들면 전날의 데이터가 사용됩니다.

반복 잠재고객 목록을 주기적으로 폴링

반복 잠재고객 목록은 추가 일수의 데이터를 사용할 수 있는 경우에만 잠재고객 목록을 생성합니다. 이렇게 하면 새 잠재고객 목록을 만들어야 하는 시기를 추측할 필요가 없습니다. 대신 하루 종일 반복 잠재고객 목록을 저렴하게 폴링하여 추가 데이터를 사용할 수 있는지 확인할 수 있습니다.

하루 동안 반복되는 잠재고객 목록을 주기적으로 폴링

반복 잠재고객 목록 만들기

반복 잠재고객 목록을 만들려면 요청에서 RecurringAudienceList 객체를 사용하여 recurringAudienceLists.create 메서드를 호출합니다. 다음 매개변수가 필요합니다.

  • audience 필드의 유효한 잠재고객 이름으로, properties/{propertyId}/audiences/{audienceId} 형식으로 지정됩니다. Google 애널리틱스 Admin API v1의 audiences.list 메서드를 사용하여 이 값을 가져올 수 있습니다. audiences.list 응답의 Audience.name 필드에는 잠재고객 이름이 포함됩니다.
  • dimensions 필드의 유효한 측정기준 목록입니다. 이 메서드에서 지원하는 측정기준 목록은 잠재고객 내보내기 스키마 문서를 참고하세요. 이 필드에 언급된 측정기준의 데이터만 잠재고객 목록에 포함됩니다.

다음은 반복 잠재고객 목록 생성 요청의 예입니다.

HTTP 요청

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

recurringAudienceLists.create 메서드의 응답에는 name 필드에 이름 (예: properties/1234567/recurringAudienceLists/123)이 포함되어 있으며, 이 이름은 후속 쿼리에서 이 반복 잠재고객 목록의 구성 메타데이터를 검색하는 데 사용할 수 있습니다. 또한 구성 메타데이터에는 이 반복 잠재고객 목록에 대해 생성된 잠재고객 목록 인스턴스의 리소스 이름이 포함됩니다.

HTTP 응답

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

구성 메타데이터 폴링

recurringAudienceLists.get 메서드를 사용하여 특정 반복 잠재고객 목록에 관한 구성 메타데이터를 가져옵니다. 구성 메타데이터에는 이 반복 잠재고객 목록에 대해 생성된 잠재고객 목록 인스턴스의 리소스 이름이 포함됩니다.

예를 들면 다음과 같습니다.

HTTP 요청

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

RecurringAudienceList 인스턴스가 응답으로 반환됩니다. 이 반복 잠재고객 목록에 대해 생성된 잠재고객 목록 인스턴스의 리소스 이름을 포함하는 구성 메타데이터가 포함되어 있습니다.

HTTP 응답

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

recurringAudienceLists.list을 사용하여 속성의 모든 반복 잠재고객 목록을 나열할 수 있습니다.

웹훅을 사용하여 새 잠재고객 목록에 관한 비동기 알림 받기

recurringAudienceLists.get 메서드를 사용하여 특정 반복 잠재고객 목록에 관한 구성 메타데이터를 주기적으로 폴링하는 대신 잠재고객 목록이 제공될 때 비동기식으로 웹훅 알림을 받을 수 있습니다.

웹훅 알림을 구성하려면 새 반복 잠재고객 목록을 만들 때 webhookNotification 필드를 지정하세요.

Google 애널리틱스 Data API v1에서 웹훅을 사용하는 방법에 관한 자세한 내용은 Async audience lists with webhooks 가이드를 참고하세요.

잠재고객 내보내기에서 사용자 가져오기

잠재고객 내보내기에서 사용자를 가져오려면 audienceExports.query 메서드를 호출하고 recurringAudienceLists.get 또는 recurringAudienceLists.list에서 제공하는 구성 메타데이터에서 가져온 잠재고객 내보내기 이름을 지정합니다.

HTTP 요청

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

잠재고객 내보내기가 준비되면 잠재고객의 사용자 목록이 포함된 응답이 반환됩니다.

HTTP 응답

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}