API v4 ของ Campaign Manager 360 ถึงวันที่หยุดให้บริการตามกำหนดการแล้ว ย้ายข้อมูลไปยัง v5 ทันที

อัปโหลด Conversion

คู่มือนี้ให้คําแนะนําโดยละเอียดสําหรับการอัปโหลด Conversion ออฟไลน์ โดยใช้บริการ Conversions ของ Campaign Manager 360 API ก่อน ดำเนินการต่อ เราขอแนะนำให้คุณอ่าน ภาพรวมเพื่อดูข้อมูลเบื้องต้นเกี่ยวกับ Conversion ออฟไลน์และ ทำความเข้าใจแนวคิดต่างๆ ที่กล่าวถึงในคู่มือนี้

กำหนดค่าแหล่งข้อมูล Conversion

ขั้นตอนแรกในกระบวนการอัปโหลด Conversion คือการสร้างออบเจ็กต์แหล่งข้อมูลอย่างน้อย 1 รายการ Conversion ออบเจ็กต์แต่ละรายการแสดงถึงเหตุการณ์ Conversion รายการเดียวและมีช่องที่ต้องระบุ 2-3 ช่อง ดังนี้

ช่อง	คำอธิบาย
`floodlightActivityId`	กิจกรรม Floodlight ที่จะเชื่อมโยงกับ Conversion นี้
`floodlightConfigurationId`	การกำหนดค่า Floodlight ที่กิจกรรมที่ระบุใช้
`ordinal`	ค่าที่ใช้ควบคุมวิธีที่ระบบกรองข้อมูล Conversion จากอุปกรณ์หรือผู้ใช้รายเดียวกันในวันเดียวกันออก ดูข้อมูลเพิ่มเติมได้ที่คำถามที่พบบ่อย
`timestampMicros`	การประทับเวลาของ Conversion เป็นไมโครวินาทีตั้งแต่ Unix Epoch

นอกจากนี้ ออบเจ็กต์แต่ละรายการต้องมีช่องต่อไปนี้ช่องใดช่องหนึ่ง

ช่อง	คำอธิบาย
`encryptedUserId`	รหัสผู้ใช้ที่เข้ารหัสรายการเดียวซึ่งได้จากมาโครการจับคู่%m หรือการโอนข้อมูล
`encryptedUserIdCandidates[]`	รายการรหัสผู้ใช้ที่เข้ารหัสซึ่งได้จากมาโครการจับคู่%m หรือการโอนข้อมูล ระบบจะใช้รหัสแรกในรายการนี้ที่มีการแสดงผล Floodlight ที่บันทึกไว้ก่อน `timestampMicros` ที่ระบุ หากไม่มีรหัสใดตรงกับการแสดงผลที่มีอยู่ ระบบจะแสดงข้อผิดพลาด
`dclid`	ตัวระบุคลิกใน Display ที่สร้างขึ้นโดย Campaign Manager 360 หรือ Display & Video 360
`gclid`	หมายเลขระบุคลิกของ Google ที่สร้างขึ้นโดย Google Ads หรือ Search Ads 360
`matchId`	ตัวระบุที่ไม่ซ้ำกันซึ่งผู้ลงโฆษณาสร้างขึ้นที่ส่งไปยัง Campaign Manager 360 ผ่านแท็ก Floodlight
`mobileDeviceId`	รหัสมือถือที่ไม่มีการเข้ารหัสในรูปแบบ IDFA หรือ รหัสโฆษณา หรือตัวระบุสําหรับการโฆษณา (IFA) บนทีวีที่เชื่อมต่ออินเทอร์เน็ตจากแพลตฟอร์มอุปกรณ์ CTV ที่รองรับ (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio)

สุดท้าย Conversion แต่ละรายการมีเมตริก 2 รายการ ดังนี้

ช่อง	คำอธิบาย
`quantity`	ต้องระบุ จํานวนรายการที่เชื่อมโยงกับ Conversion ต้องมีอย่างน้อย 1 รายการเพื่อให้ Conversion นับรวมในเมตริกบางรายการ (เช่น Conversion ทั้งหมด)
`value`	จํานวนเงินดอลลาร์ที่เชื่อมโยงกับ Conversion ซึ่งตีความตามสกุลเงินของผู้ลงโฆษณาที่เป็นเจ้าของการกำหนดค่า Floodlight

ช่องที่ไม่บังคับจะอธิบายไว้ในเอกสารอ้างอิง

ตัวอย่างด้านล่างแสดงการสร้างออบเจ็กต์แหล่งข้อมูล Conversion แบบง่าย

C#

// Generate a timestamp in milliseconds since Unix epoch.
TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1);
long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds;

// Find the Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity =
    service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute();
long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId;

// Create the conversion.
Conversion conversion = new Conversion();
conversion.EncryptedUserId = conversionUserId;
conversion.FloodlightActivityId = floodlightActivityId;
conversion.FloodlightConfigurationId = floodlightConfigurationId;
conversion.Ordinal = currentTimeInMilliseconds.ToString();
conversion.TimestampMicros = currentTimeInMilliseconds * 1000;

Java

long currentTimeInMilliseconds = System.currentTimeMillis();

// Find Floodlight configuration ID based on the provided activity ID.
FloodlightActivity floodlightActivity = reporting.floodlightActivities()
    .get(profileId, floodlightActivityId).execute();
long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId();

Conversion conversion = new Conversion();
conversion.setEncryptedUserId(encryptedUserId);
conversion.setFloodlightActivityId(floodlightActivityId);
conversion.setFloodlightConfigurationId(floodlightConfigurationId);
conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds));
conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);

PHP

$currentTimeInMicros = time() * 1000 * 1000;

// Find Floodlight configuration ID based on provided activity ID.
$activity = $this->service->floodlightActivities->get(
    $values['user_profile_id'],
    $values['floodlight_activity_id']
);
$floodlightConfigId = $activity->getFloodlightConfigurationId();

$conversion = new Google_Service_Dfareporting_Conversion();
$conversion->setEncryptedUserId($values['encrypted_user_id']);
$conversion->setFloodlightActivityId($values['floodlight_activity_id']);
$conversion->setFloodlightConfigurationId($floodlightConfigId);
$conversion->setOrdinal($currentTimeInMicros);
$conversion->setTimestampMicros($currentTimeInMicros);

Python

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = (
    service.floodlightActivities()
    .get(profileId=str(profile_id), id=str(floodlight_activity_id))
    .execute()
)
floodlight_config_id = floodlight_activity['floodlightConfigurationId']

current_time_in_micros = int(time.time() * 1000000)

# Construct the conversion.
conversion = {
    'encryptedUserId': encrypted_user_id,
    'floodlightActivityId': floodlight_activity_id,
    'floodlightConfigurationId': floodlight_config_id,
    'ordinal': current_time_in_micros,
    'timestampMicros': current_time_in_micros
}

Ruby

# Look up the Floodlight configuration ID based on activity ID.
floodlight_activity = service.get_floodlight_activity(profile_id,
  floodlight_activity_id)
floodlight_config_id = floodlight_activity.floodlight_configuration_id

current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000

# Construct the conversion.
conversion = DfareportingUtils::API_NAMESPACE::Conversion.new(
  encrypted_user_id: encrypted_user_id,
  floodlight_activity_id: floodlight_activity_id,
  floodlight_configuration_id: floodlight_config_id,
  ordinal: current_time_in_micros,
  timestamp_micros: current_time_in_micros
)

ระบุข้อมูลการเข้ารหัส

หากคุณวางแผนที่จะระบุแหล่งที่มาของ Conversion ออฟไลน์เป็นรหัสผู้ใช้ที่เข้ารหัส ดังเช่นในตัวอย่างก่อนหน้า คุณจะต้องระบุรายละเอียดบางอย่างเกี่ยวกับวิธีเข้ารหัสรหัสเหล่านั้นเป็นส่วนหนึ่งของคําขอแทรก โดยเฉพาะอย่างยิ่ง คุณจะต้องทราบข้อมูลต่อไปนี้

**แหล่งที่มาของการเข้ารหัส** ซึ่งอธิบายว่าชุดรหัสที่เข้ารหัส ได้มาจากที่ใด ค่าที่ยอมรับได้คือ AD_SERVING สําหรับรหัสที่ได้จากมาโครการจับคู่ %m หรือ DATA_TRANSFER สําหรับรหัสที่ได้จากไฟล์การโอนข้อมูล
เอนทิตีการเข้ารหัส ซึ่งเป็นชุดค่าที่ไม่ซ้ำกันที่ใช้ในการเข้ารหัส รหัสผู้ใช้ โดยปกติแล้วค่าเหล่านี้จะเกี่ยวข้องกับบัญชี Campaign Manager 360 เมื่อแหล่งที่มาคือการโอนข้อมูล หรือผู้ลงโฆษณา Campaign Manager 360 เมื่อแหล่งที่มาคือมาโคร %m แต่ก็ไม่เสมอไป หากไม่แน่ใจ โปรดติดต่อ ตัวแทนบัญชี Campaign Manager 360 หรือ ทีมสนับสนุนของ Campaign Manager 360 เพื่อขอข้อมูลเพิ่มเติม

เมื่อจําเป็น การสร้างออบเจ็กต์ EncryptionInfo ที่ระบุค่าเหล่านี้จะเป็นขั้นตอนที่ 2 ในกระบวนการอัปโหลด Conversion

C#

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.EncryptionEntityId = encryptionEntityId;
encryptionInfo.EncryptionEntityType = encryptionEntityType;
encryptionInfo.EncryptionSource = encryptionSource;

Java

// Create the encryption info.
EncryptionInfo encryptionInfo = new EncryptionInfo();
encryptionInfo.setEncryptionEntityId(encryptionEntityId);
encryptionInfo.setEncryptionEntityType(encryptionEntityType);
encryptionInfo.setEncryptionSource(encryptionSource);

PHP

$encryptionInfo = new Google_Service_Dfareporting_EncryptionInfo();
$encryptionInfo->setEncryptionEntityId($values['encryption_entity_id']);
$encryptionInfo->setEncryptionEntityType($values['encryption_entity_type']);
$encryptionInfo->setEncryptionSource($values['encryption_source']);

Python

# Construct the encryption info.
encryption_info = {
    'encryptionEntityId': encryption_entity_id,
    'encryptionEntityType': encryption_entity_type,
    'encryptionSource': encryption_source
}

Ruby

# Construct the encryption info.
encryption_info = DfareportingUtils::API_NAMESPACE::EncryptionInfo.new(
  encryption_entity_id: encryption[:entity_id],
  encryption_entity_type: encryption[:entity_type],
  encryption_source: encryption[:source]
)

โปรดทราบว่าคําขอแทรกแต่ละรายการจะมีออบเจ็กต์ EncryptionInfo ได้เพียงรายการเดียว ซึ่งหมายความว่า Conversion ทั้งหมดที่รวมอยู่ในคําขอที่ระบุต้องมาจากแหล่งที่มาเดียวกันและใช้เอนทิตีการเข้ารหัสเดียวกัน

สร้างคําขอแทรก

ขั้นตอนสุดท้ายในกระบวนการนี้คือการอัปโหลด Conversion ด้วยการเรียก batchinsert เมธอดนี้ยอมรับออบเจ็กต์ ConversionsBatchInsertRequest ซึ่งรวมชุด Conversion ที่จะอัปโหลดเข้ากับข้อมูลการเข้ารหัสที่เกี่ยวข้อง (เมื่อจําเป็น)

C#

// Insert the conversion.
ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.Conversions = new List<Conversion>() { conversion };
request.EncryptionInfo = encryptionInfo;

ConversionsBatchInsertResponse response =
    service.Conversions.Batchinsert(request, profileId).Execute();

Java

ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest();
request.setConversions(ImmutableList.of(conversion));
request.setEncryptionInfo(encryptionInfo);

ConversionsBatchInsertResponse response = reporting.conversions()
    .batchinsert(profileId, request).execute();

PHP

$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest();
$batch->setConversions([$conversion]);
$batch->setEncryptionInfo($encryptionInfo);

$result = $this->service->conversions->batchinsert(
    $values['user_profile_id'],
    $batch
);

Python

# Insert the conversion.
request_body = {
    'conversions': [conversion],
    'encryptionInfo': encryption_info
}
request = service.conversions().batchinsert(
    profileId=str(profile_id), body=request_body
)
response = request.execute()

Ruby

# Construct the batch insert request.
batch_insert_request =
  DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new(
    conversions: [conversion],
    encryption_info: encryption_info
  )

# Insert the conversion.
result = service.batchinsert_conversion(profile_id, batch_insert_request)

โปรดทราบว่า Campaign Manager 360 จะพยายามแทรก Conversion แต่ละรายการในคําขอของคุณตามความพยายามอย่างเต็มที่ แทนที่จะแทรกทั้งชุดเป็นธุรกรรมแบบทั้งหมดหรือไม่มีเลย หาก Conversion บางรายการในชุดแทรกไม่สําเร็จ Conversion อื่นๆ อาจยังคงแทรกได้สําเร็จ ดังนั้น เราขอแนะนําให้คุณตรวจสอบ ที่แสดงผล ConversionsBatchInsertResponseเพื่อ ดูสถานะของ Conversion แต่ละรายการ

C#

// Handle the batchinsert response.
if (!response.HasFailures.Value) {
  Console.WriteLine("Successfully inserted conversion for encrypted user ID {0}.",
      conversionUserId);
} else {
  Console.WriteLine("Error(s) inserting conversion for encrypted user ID {0}:",
      conversionUserId);

  ConversionStatus status = response.Status[0];
  foreach(ConversionError error in status.Errors) {
    Console.WriteLine("\t[{0}]: {1}", error.Code, error.Message);
  }
}

Java

if (!response.getHasFailures()) {
  System.out.printf("Successfully inserted conversion for encrypted user ID %s.%n",
      encryptedUserId);
} else {
  System.out.printf("Error(s) inserting conversion for encrypted user ID %s:%n",
      encryptedUserId);

  // Retrieve the conversion status and report any errors found. If multiple conversions
  // were included in the original request, the response would contain a status for each.
  ConversionStatus status = response.getStatus().get(0);
  for (ConversionError error : status.getErrors()) {
    System.out.printf("\t[%s]: %s.%n", error.getCode(), error.getMessage());
  }
}

PHP

if (!$result->getHasFailures()) {
    printf(
        'Successfully inserted conversion for encrypted user ID %s.',
        $values['encrypted_user_id']
    );
} else {
    printf(
        'Error(s) inserting conversion for encrypted user ID %s:<br><br>',
        $values['encrypted_user_id']
    );

    $status = $result->getStatus()[0];
    foreach ($status->getErrors() as $error) {
        printf('[%s] %s<br>', $error->getCode(), $error->getMessage());
    }
}

Python

if not response['hasFailures']:
  print(
      'Successfully inserted conversion for encrypted user ID %s.'
      % encrypted_user_id
  )
else:
  print(
      'Error(s) inserting conversion for encrypted user ID %s.'
      % encrypted_user_id
  )

  status = response['status'][0]
  for error in status['errors']:
    print('\t[%s]: %s' % (error['code'], error['message']))

Ruby

if result.has_failures
  puts format('Error(s) inserting conversion for encrypted user ID %s.',
    encrypted_user_id)

  status = result.status[0]
  status.errors.each do |error|
    puts format("\t[%s]: %s", error.code, error.message)
  end
else
  puts format('Successfully inserted conversion for encrypted user ID %s.',
    encrypted_user_id)
end

ช่อง status ของการตอบกลับ ดังที่เห็นด้านบน จะมีออบเจ็กต์ ConversionStatus สําหรับ Conversion ทุกรายการที่รวมอยู่ในคําขอเดิม หากคุณสนใจเฉพาะ Conversion ที่แทรกไม่สําเร็จ คุณสามารถใช้ช่อง hasFailures เพื่อตรวจสอบอย่างรวดเร็วว่า Conversion ใดๆ ในชุดที่ระบุแทรกไม่สําเร็จหรือไม่

ยืนยันว่าระบบประมวลผล Conversion แล้ว

โดยทั่วไปแล้วระบบจะประมวลผล Conversion ที่อัปโหลดและพร้อมให้รายงานภายใน 24 ชั่วโมง หากต้องการยืนยันว่าระบบประมวลผล Conversion ที่คุณอัปโหลดแล้วหรือไม่ เราขอแนะนําให้เรียกใช้รายงานการแสดงผล Floodlight Impressions รายงานเหล่านี้จะแสดงผลทั้ง Conversion ที่ระบุแหล่งที่มา (เชื่อมโยงกับโฆษณา) และ Conversion ที่ไม่ได้ระบุแหล่งที่มาโดยค่าเริ่มต้น ซึ่งแตกต่างจากรายงานการระบุแหล่งที่มาอื่นๆ จึงเหมาะอย่างยิ่งสําหรับการตรวจสอบอย่างรวดเร็วว่า Conversion ที่คุณส่งมาถึง Campaign Manager 360 แล้วหรือไม่