jQueryを使用してフォームを操作する方法を教えてください。

.val()または.prop()を使用してフォームの入力値を操作する場合、change()またはtrigger('change')を使用して変更イベントをトリガーすることにより、変更を適切に登録する必要があります。

HubSpotフォームはDOMの構築後にレンダリングされるため、ウィンドウの読み込み後に操作をトリガーするか、onFormReadyパラメーターを使用するように埋め込みに変更を加える必要があります。

Update fields when page finishes loading: $(window).load(function(){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); }); Modified embed code to update fields when form builds: hbspt.forms.create({ portalId: 'XXXXXX', formId: 'aa8b5b4a-62ac-461b-a387-XXXXXXXXXXX', onFormReady: function($form, ctx){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); } });

HubSpotのAPIによるタイムスタンプの形式はどのように設定すればよいですか？

レスポンスの時刻値はISO 8601形式で表記されますが、APIでは日付と時刻の値について、次の2つの形式の両方を受け入れます。
  • ISO 8601形式の文字列：データ型に応じて、次のいずれかの形式になります。
    • 特定の日付を表す値の場合、次のような完全日付形式が使用されます：YYYY-MM-DD（例：2020-02-29）
    • 特定の日時を表す値の場合、完全な日付形式に時、分、秒、および秒小数部分を追加した次の形式が使用されます：YYYY-MM-DDThh:mm:ss.sTZD（例：2020-02-29T03:30:17.000Z）。時刻は常にUTCで表現されるため、値には必ずUTC指定子「Z」が使用されます。
  • UNIX形式のタイムスタンプ（ミリ秒単位）：UTC時間で表される、ミリ秒単位のタイムスタンプ値。例えば、タイムスタンプ値「1427997766000」は、「2015年4月2日の18:02:46 UTC」、つまり「2015年4月2日の午後2:02:46 EDT（米国東部夏時間）」を表します。

HubSpot CRMでの日付と日時のプロパティー

HubSpotには、時間を保存するためのCRMオブジェクトプロパティーとして、dateとdatetimeの2種類があります。

  • dateプロパティー（HubSpotで作成されるdate pickerプロパティーを含む）は、時間ではなく日付を保存します。dateプロパティーには、アカウントやユーザーのタイムゾーン設定に関係なく、設定されている日付が表示されます。dateプロパティー値では、ISO 8601の完全な日付形式を使用することをお勧めします。UNIXタイムスタンプ形式を使用する場合は、エポックミリ秒タイムスタンプを使用する必要があります（つまり、対象となる日付のUTCの深夜の値に設定する必要があります）。例えば、それぞれの形式で2015年5月1日を表す場合は、次のようになります。
    • IOS 8601：2015-05-01
    • エポックミリ秒タイムスタンプ：1430438400000

注：dateプロパティーのUNIXタイムスタンプを使用している場合に、UTCの深夜以外の値を設定しようとすると、エラーが返されます。

  • datetimeプロパティーには、日付と時刻の両方が保存されます。両方のタイムスタンプ形式が受け入れられます。HubSpotのdatetimeのプロパティーは、レコードを表示するユーザーのタイムゾーンに基づいて表示されるため、値はユーザーのローカル タイム ゾーンに変換されます。HubSpot上に作成したdate pickerプロパティーは、dateプロパティーになるため、datetimeプロパティーの唯一の作成方法はAPIを使用することです。貴社の連携において特定の時刻を保持する必要がある場合は、プロパティーエンドポイントを使用してカスタムdatetimeプロパティーを作成することができます。

APIのエラーメッセージに関する留意点はありますか？

特に明記されていない限り、大半のHubSpotエンドポイントでは、正常に完了した場合に200 OKのレスポンスが返されます。他のステータスコードを返すエンドポイントについては、エンドポイントのドキュメントに、どのレスポンスが返されるかが明記されています。

さらに、HubSpotには、複数のAPIに共通する次のようなエラーレスポンスがあります。

  • 401 Unauthorized - APIに渡された認証情報が無効な場合、このエラーレスポンスが返されます。APIリクエストの認証については、認証の概要（英語）を参照してください。
  • 403 Forbidden - APIに渡された認証対象にその特定のURLに対するアクセス権限が付与されていない場合、このエラーレスポンスが返されます。例えば、コンテンツのアクセス権限しか付与されていないOAuthトークンによって取引API（コンタクトアクセス権限が必要）にアクセスしようとすると、403が返されます。
  • 429 Too many requests - アカウントまたはアプリが、該当するAPIレート制限（英語）を超えている場合、このエラーレスポンスが返されます。レート制限を順守するための推奨事項については、こちら（英語）に記載しています。
  • 502／504 timeouts - HubSpotには、単一のクライアントに起因するパフォーマンスの低下を防止するためのプロセス制限が設けられています。このレスポンスは、その制限に達したことを意味します。通常、このようなタイムアウトレスポンスが表示されるのは、長時間にわたり大量のリクエストを送信している場合に限られます。これらのレスポンスのいずれかが表示されたら、数秒間リクエストを一時停止してから再試行してください。

上記の全般的なエラーを除いて、HubSpotのエラーレスポンスは基本的に読みやすく記述されています。ほとんどのエンドポイントから、エラーコードではなく、エラーに関する詳細を記載したJSON形式のレスポンスが返されます。エンドポイント固有のエラーの詳細は、該当するエンドポイントのドキュメントページに記載されています。

注：以下のレスポンスの例に示されている全てのフィールドは、エラー解析時には任意指定として扱ってください。APIごとに使用する具体的なフィールドは異なるため、エラー解析では、レスポンスに特定のフィールドが欠落していても許容する必要があります。

{"status":"error","message":"This will be a human readable message with details about the error.","errors":[{"message":"This will be a message with additional details about the error","in":"name"}],"category":"VALIDATION_ERROR","correlationId":"a43683b0-5717-4ceb-80b4-104d02915d8c"}

HubSpot APIではCORS／AJAXリクエストがサポートされますか？

ほとんどの場合、HubSpot APIにおいてクロスオリジン（CORS）AJAXリクエストはサポートされません。クライアントサイドでJavaScriptを使用してリクエストを送信すると、そのリクエストで使用している認証情報が公開されてしまいます。JavaScript／AJAXを使用するには、（認証情報を除く）リクエストを外部サーバーに送信し、必要な認証情報を追加してから、HubSpot APIのサーバーサイドにリクエストを送信する必要があります。

このルールには、次の例外があります。

HubSpotでは、Eメールアドレスはどのように検証されますか？

HubSpotでは、コンタクトレコードの作成または更新のプロセスに使用されるEメールアドレスが検証されます。コンタクトエンドポイントを使用したコンタクトの作成または更新以外に、フォーム送信（英語）やイベント（英語）も同様です。

こうしたプロセスでは、（埋め込みフォームの場合のように）Eメールアドレス自体の有効性がチェックされるのではなく、その形式がチェックされます。RFC 2822に準拠した有効性に加えて、HubSpotではEメールアドレスに関する次の制限も適用されます。

  • アドレスのローカル部分に引用符を含めることはできません（例："Test Email"@hubspot.comは無効）。
  • https://data.iana.org/TLD/tlds-alpha-by-domain.txtに記載されているように、ドメインの部分は有効なTLDで終わる必要があります（この制限はUnicode TLDの処理後に適用されるため、「user@email.삼성」は有効なEメールアドレスです）。

チェックボックスのプロパティーに複数の値を設定する方法を教えてください。

チェックボックスのプロパティーに複数の値を設定するには、値をセミコロン（;）で区切る必要があります。
例：'value1;value2;value5'

CRMオブジェクトエンドポイントを介してレコードを更新する場合、プロパティー値は、全てセミコロンで区切られた値から成る単一の文字列にする必要があります。

{
  "properties":
    {
      "example_property": "value1;value3;value4"
    }
}

フォームエンドポイントの場合は、セミコロンについてもURLエンコードする必要があります。

...&example_property=value1%3Bvalue2%3Bvalue4

コンタクトレコードに関する制限はありますか？

HubSpotでは、マージされるコンタクトレコードに関して、またコンタクトレコードのフォーム送信に関していくつかの制限が設けられています。

  1. リンクできるIDは、コンタクトあたり最大250個に制限されています。
    • 2つのコンタクトをマージしようとして、その結果、コンタクトあたりのIDが250個を超える場合は、エラーが返されます。
  2. コンタクトのフォーム送信は最大1,000件に制限されています。コンタクトがこの制限を超えることになる送信は、完全に破棄されます。
    • このフォームデータによるコンタクトレコードの更新は行われません。
    • コンタクトエンドポイントからのform-submissionsデータにも、コンタクトのタイムラインにも、コンタクトレコードに関する送信自体が示されません。
    • この送信には、リストメンバーシップまたはワークフローに関する評価が行われません。
    • この送信はHubSpot上でフォームを表示した場合の送信リストに表示されません。

テストが原因で以上のいずれかの上限を超えた場合、テストコンタクトを削除し、新しいテストレコードを作成することをお勧めします。新しいコンタクトに同じEメールアドレスを使用しても、削除済みのコンタクトは復元されません。そのEメールでのフォーム送信は、新しいレコードに関連付けられます。

トランザクションEメールの送信方法を教えてください。

HubSpotではトランザクションEメールの送信方法として、SMTP APIと1回送信APIの2つが用意されています。

SMTP APIの使用

SMTP APIは、Eメールの送信を直接行いませんが、HubSpot SMTPサーバーへのログイン資格情報を取得するためにだけ使用されます。SMTP APIを使用してトークンとパスワードを取得した後、これらの資格情報を使用してHubSpotのSMTPサーバーにログインし、SMTP経由でEメールを送信する必要があります。SMTPサーバーへのログイン詳細（ホスト名とポート）は、ドキュメントページ（英語）で説明します。HubSpotのEメールトラッキングをサポートするためにEメールとリンクはラッピングされますが、それ以外のEメールコンテンツ全体はご自身で作成する必要があります。

1回送信APIの使用

1回送信APIでは、HubSpotのEメールツールで作成したテンプレートEメールとJSON形式のPOST APIを使用して、Eメールが送信されます。まず、HubSpotでEメールを作成し、受信者を選択する際に［1回送信API用に保存］を選択する必要があります。Eメールが作成されたら、APIリクエストの本文で受信者の詳細（Eメールでセットアップしたコンタクトやカスタムプロパティーを含む）を設定した上で、APIを使用してコンタクトにEメールを送信できます。JSONリクエストの形式については、このドキュメントページ（英語）で説明します。

APIに関する最新情報の受信方法を教えてください。

HubSpotのAPIと開発者ツールに関する最新情報は、開発者変更ログ（英語）で提供しています。

左側のフォームを使用して最新情報の受信登録ができます。発表と同時に通知を受けるには、頻度として［Instant］を選択します。他の頻度を選択して、最適な頻度で最新情報の要約を受け取ることもできます。

HubSpotプラットフォームを利用してプライバシーおよび法令順守に対応する方法を教えてください。

HubSpotでデータを処理するための法的根拠のトラッキング

GDPR（EU一般データ保護規則）により、企業が連絡先情報を使用、処理するためには法的根拠が必要となり、情報の提供者による同意と、合法的な処理方法を示す証拠を記録に残すことが義務化されました。

［コンタクトのデータを処理するための法的根拠］というコンタクトプロパティーでは、契約や正当な利害関係、および／または同意に基づくHubSpotのコンタクトに関するデータ処理の法的根拠を収集、追跡、保存することができます。

コンタクトエンドポイントを介してコンタクトデータにアクセスする場合、このプロパティーではhs_legal_basisという名前が使用されます。他のコンタクトのプロパティーと同じように、このプロパティーが設定されたコンタクトにはAPI経由のアクセスが可能です。このプロパティーは、APIを介して、コンタクトレコードに関して更新したり設定したりすることもできます。

ただし、このプロパティーのオプションに対して、API経由で変更を加えることはできません。更新はHubSpot内に限定されますが、このプロパティーに設定されているカスタムオプションをコンタクト プロパティー エンドポイント経由で取得することは可能です。HubSpotアカウントによっては既定とは異なる設定が使用されている場合もあるため、このようなエンドポイントを使用してプロパティーのオプションを取得することをお勧めします。

このプロパティーの詳細とHubSpotでの使い方については、こちらを参照してください：
ナレッジベース記事。

プライバシー規則に準拠したコンタクト削除の処理

HubSpotユーザーは、プライバシーに関する法律に準拠するためにコンタクトレコードを完全に削除することができます。詳細については、こちらのナレッジベース記事を参照してください。

contact.privacyDeletion配信カテゴリー(サブスクリプションタイプ)の受信を登録することにより、ユーザーがプライバシー順守のためのコンタクト削除を実行したときにWebhook通知を受信できます。Webhookの詳細とWebhook通知を処理する（英語）方法については、Webhookの概要（英語）を参照してください。