잠재고객 구성원 보내기

이 빠른 시작을 통해 데이터 관리 도구 API에 익숙해질 수 있습니다. 확인하려는 빠른 시작 버전을 선택합니다.

이 빠른 시작에서는 다음 단계를 완료합니다.

  1. 잠재고객 데이터를 수신할 Destination를 준비합니다.
  2. 전송할 잠재고객 데이터를 준비합니다.
  3. 잠재고객 구성원을 위한 IngestionService 요청을 빌드합니다.
  4. Google API 탐색기로 요청을 보냅니다.
  5. 성공 및 실패 응답을 이해합니다.

대상 준비

데이터를 전송하려면 먼저 데이터를 전송할 대상을 준비해야 합니다. 다음은 사용할 수 있는 샘플 Destination입니다.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

  • operatingAccount를 잠재고객 데이터를 수신할 계정의 계정 유형 및 ID로 설정합니다.

시청자 데이터 준비

쉼표로 구분된 파일의 다음 샘플 데이터를 고려해 보세요. 파일의 각 줄은 잠재고객의 한 구성원에 해당하며 각 구성원에게는 최대 3개의 이메일 주소가 있습니다.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

이메일 주소에는 다음과 같은 형식 및 해싱 요구사항이 있습니다.

  1. 모든 선행, 후행, 중간 공백을 삭제합니다.
  2. 이메일 주소를 소문자로 변환합니다.
  3. SHA-256 알고리즘을 사용하여 이메일 주소를 해싱합니다.
  4. 16진수 (hex) 또는 Base64 인코딩을 사용하여 해시 바이트를 인코딩합니다. 이 가이드의 예시에서는 16진수 인코딩을 사용합니다.

형식이 지정된 데이터는 다음과 같습니다.

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

해싱 및 인코딩된 데이터는 다음과 같습니다.

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

다음은 입력 데이터의 첫 번째 행에 있는 dana@example.com 및 danam@example.com의 형식이 지정되고, 해싱되고, 인코딩된 이메일 주소의 샘플 AudienceMember입니다.

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

요청 본문 빌드

요청 본문의 Destination 및 userData을 결합합니다.

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
  1. 본문의 자리표시자(예: OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID, AUDIENCE_ID)를 계정 및 대상의 값으로 업데이트합니다.
  2. validateOnly을 true로 설정하여 변경사항을 적용하지 않고 요청을 검증합니다. 변경사항을 적용할 준비가 되면 validateOnly을 false로 설정합니다.
  3. 사용자가 고객 일치 타겟팅 서비스 약관에 동의했음을 나타내도록 termsOfService를 설정합니다.
  4. 이 요청은 consent이 부여되었으며 암호화를 사용하지 않음을 나타냅니다.

요청 전송

  1. 샘플 오른쪽 상단의 복사 버튼을 사용하여 요청 본문을 복사합니다.
  2. 툴바에서 API 버튼을 클릭합니다.
  3. 복사한 요청 본문을 요청 본문 상자에 붙여넣습니다.
  4. 실행 버튼을 클릭하고 승인 메시지를 완료한 후 응답을 검토합니다.

성공 응답

요청에 성공하면 requestId가 포함된 객체가 있는 응답이 반환됩니다.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

요청의 각 대상이 처리될 때 진단을 검색할 수 있도록 반환된 requestId을 기록합니다.

실패 응답

요청이 실패하면 400 Bad Request와 같은 오류 응답 상태 코드와 오류 세부정보가 포함된 응답이 반환됩니다.

예를 들어 16진수 인코딩 값 대신 일반 텍스트 문자열이 포함된 email_address는 다음 응답을 생성합니다.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

해싱되지 않고 16진수로만 인코딩된 email_address는 다음 응답을 생성합니다.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

여러 대상에 이벤트 전송

데이터에 여러 대상의 잠재고객 구성원이 포함되어 있는 경우 대상 참조를 사용하여 동일한 요청으로 전송할 수 있습니다.

예를 들어 사용자 목록 ID 11112222의 잠재고객 구성원과 사용자 목록 ID 77778888의 잠재고객 구성원이 있는 경우 각 Destination의 reference를 설정하여 단일 요청으로 두 잠재고객 구성원을 모두 전송합니다. reference는 사용자가 정의합니다. 유일한 요구사항은 각 Destination에 고유한 reference가 있어야 한다는 것입니다. 요청에 맞게 수정된 destinations 목록은 다음과 같습니다.

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

하나 이상의 특정 대상으로 전송되도록 각 AudienceMember의 destination_references를 설정합니다. 예를 들어 다음은 첫 번째 Destination에만 적용되는 AudienceMember이므로 destination_references 목록에는 첫 번째 Destination의 reference만 포함됩니다.

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

destination_references 필드는 목록이므로 잠재고객 구성원의 대상을 여러 개 지정할 수 있습니다. AudienceMember의 destination_references를 설정하지 않으면 Data Manager API가 요청의 모든 대상으로 잠재고객 구성원을 전송합니다.

다음 단계

이전
잠재고객 개요