Skip to content
AMPScript - Salesforce
Share
Explore

icon picker
AMPScript | Parte 01

AMPScript é uma linguagem de script usada na plataforma Salesforce Marketing Cloud. Ela permite personalizar e automatizar processos de marketing de maneira eficaz e direcionada. Em vez de escrever código detalhado, os profissionais de marketing podem usar AMP

1. Linguagem

1.1. Sintaxe

Como o AMPscript é um idioma do lado do servidor, o código pode ser incluído em qualquer local em um email, página da web, SMS ou mensagem push. Semelhante a outras linguagens de script, o AMPscript é interpretado e não compilado, o que significa que é interpretado na ordem em que é escrito. Portanto, se você estiver usando o AMPscript para incluir conteúdo personalizado em um email, o código AMPscript precisará ser definido antes ou no ponto em que o conteúdo personalizado deve aparecer.

1.2. Em bloco de AMPscript

O código AMPScript está contido em uma sequência de caracteres que abre e fecha com duas marcas percentuais %% e contém um delimitador de suporte interno [ e ]
%%[
/* Bloco de AMPScript */
var @nome, @idade
set @nome = "Maria"
set @idade = 30

if @idade >= 18 then
outputline("Olá ", @nome, "! Você é maior de idade.")
else
outputline("Olá ", @nome, "! Você é menor de idade.")
endif
]%%
Os blocos AMPscript são usados para definir o código para interpretação, mas não exibem a saída onde o código aparece no email ou na página. Existem algumas exceções a esta regra através do fornecimento de duas funções Saída e OutputLine, que habilitam variável valores a serem emitidos no local em que o bloco de código aparece.

1.3. Em linha de AMPscript

O código AMPScript está contido em uma sequência de caracteres que abre e fecha com duas marcar percentuais %% e contém um delimitador de suporte interno = e =
Olá %%=v(@nome)=%%, hoje é %%=Now()=%%.
O AMPscript embutido fornece um método conveniente de interpretar e executar uma função no conteúdo da mensagem. Diferentemente dos blocos AMPscript, o AMPscript em linha só pode ser usado com uma única função e a saída da função é exibida onde o código AMPscript em linha aparece. No entanto, funções aninhadas são suportadas.

1.4. Sintaxe baseada em tags

Como alternativa à sintaxe do bloco AMPscript, a tag do script HTML também é suportada. Essa sintaxe pode ser benéfica ao desenvolver em SSJS (Server-Side JavaScript) e AMPscript, pois fornece uma sintaxe padronizada para interpretar os dois idiomas de script do lado do servidor.
Os atributos de runat e language adicionais devem ser incluídos na tag de script de abertura para que o código que contém seja interpretado como AMPscript, conforme indicado no exemplo abaixo:
<script runat="server" language="ampscript">/* Código AMPscript */</script>

1.5. Funções

Na programação, a função é uma seção nomeada de um programa que usa alguns valores de entrada (ou argumentos) para executar uma tarefa específica e produzir um valor de saída. Enquanto outras linguagens de script oferecem funções definidas pelo usuário (por exemplo, JavaScript), o AMPscript usa uma abordagem declarativa por meio de funções predefinidas, orientadas principalmente para exibir, transformar e armazenar dados e conteúdo de marketing do clientes.
As funções do AMPscript funcionam da mesma maneira que no Microsoft Excel; isto é, os parâmetros são definidos para uma função predefinida, que é interpretada e, por sua vez, retorna um valor. Várias funções do AMPscript são idênticas às funções do Excel - enquanto algumas funções são nomeadas de maneira diferente, elas compartilham os mesmos parâmetros e produzem o mesmo resultado que o Excel.

1.5.1. AMPScript e Excel

Há um total de 15 funções comparáveis entre Excel e AMPscript que aceitam os mesmos parâmetros e emitem o mesmo resultado, conforme indicado na tabela abaixo.
Funções
0
CHAR
Char
CONCATENATE
Concat
FIND
IndexOf
IF
IIf
ISBLANK
Empty
LEN
Length
LOWER
Lowercase
MOD
Mod
NOW
Now
PROPER
ProperCase
RANDBETWEEN
Random
SUBSTITUTE
Replace
SUM
Add
TRIM
Trim
UPPER
Uppercase

1.6. Variáveis

Semelhante a outras linguagens de programação e script, o AMPscript oferece suporte a variáveis ​​. Na programação, as variáveis ​​fornecem um método conveniente de definir uma função ou valor uma vez e, em seguida, reutilizar essa variável referenciando-a no código. Isso é da mesma forma que as classes Cascading Style Sheets (CSS) são definidas uma vez e, em seguida, as propriedades de estilo definidas são aplicadas a um ou mais elementos, incluindo o nome da classe em um atributo de classe. No entanto, as variáveis ​​não apenas permitem que valores fixos (ou ) sejam definidos uma vez, mas também funções AMPscript e, por sua vez, o valor de saída da variável pode mudar dependendo do contexto para o qual é interpretado.

1.6.1. Convenção de nomes

As variáveis ​​são essencialmente 'contêineres nomeados', onde um nome definido pelo usuário é aplicado a uma entidade definida, seja uma constante ou função. Os nomes de variáveis ​​não diferenciam maiúsculas de minúsculas e podem incluir caracteres ou números, mas não espaços ou vírgulas. Os nomes das variáveis ​​devem começar @ e incluir pelo menos uma outra letra, número ou sublinhado. Você deve considerar a nomeação de variáveis ​​com uma taxonomia legível por humanos que tenha significado ou contexto para outras pessoas, para que seu código seja fácil de interpretar e não exija engenharia reversa para compreender sua finalidade.
Por exemplo, se você estiver definindo uma variável que deriva um valor de pontuação de propensão dos dados do cliente, considere usar um nome como @propensityScore , não @ps. Além disso, pode ser útil aplicar a notação camel case para nomes de variáveis ​​que são compostos por mais de uma palavra colocando as palavras subsequentes em maiúsculas. Por exemplo, uma variável nomeada @preferredContactNumber é mais fácil de ler do que @preferredcontactnumber.

1.6.2. Declarando variáveis

Antes que uma variável possa ser definida , ela deve ser declarada. As variáveis ​​são declaradas com a var palavra-chave, seguida por um ou mais nomes de variáveis ​​delimitados por vírgulas. Por exemplo, se você precisar definir o nome, o sobrenome e a data de expiração da associação de um membro, as variáveis ​​podem ser declaradas como:
var @firstName, @lastName, @membershipExpiryDate
declaração de uma variável adiciona uma entrada a um Dicionário de variáveis ​​interno, usando o nome da variável como chave e null como valor. Se já existir uma entrada para esse nome, o valor da variável será redefinido para null.
NOTA: AMPscript é uma linguagem de tipagem flexível e, como resultado, o interpretador não obriga a declaração de variáveis. No entanto, é uma prática recomendada fazer isso para garantir que o nome da variável seja adicionado ao Dicionário de variáveis.

1.6.3. Variáveis de configurações

Depois que uma variável é declarada, ela pode ser definida. As variáveis ​​são definidas usando uma sintaxe que compreende quatro elementos:
a set palavra-chave
o nome da variável
um único símbolo de igual (=)
uma string de personalização , constante ou função AMPscript (que pode conter funções aninhadas).
Consulte o exemplo abaixo, onde as variáveis ​​são definidas como uma string de personalização ( @firstName), função AMPscript ( @localDate) e constante ( @promotionEndDate):
%%[
var @firstName, @localDate, @promotionEndDate
set @firstName = FirstName
set @localDate = SystemDateToLocalDate(Now())
set @promotionEndDate = '10/15/2018'
]%%
var @firstName, @localDate, @promotionEndDate: Aqui, três variáveis são declaradas: @firstName, @localDate e @promotionEndDate.
set @firstName = FirstName: Essa linha atribui o valor da variável personalizada FirstName à variável @firstName.
set @localDate = SystemDateToLocalDate(Now()): Aqui, a função Now() é usada para obter a data e a hora atuais do sistema no formato GMT (hora padrão). Em seguida, a função SystemDateToLocalDate() é usada para converter essa data e hora para o fuso horário local. O resultado é armazenado na variável @localDate
set @promotionEndDate = '10/15/2018': Aqui, uma data específica, neste caso, '10/15/2018', é atribuída à variável @promotionEndDate. Isso pode indicar a data de término de uma promoção ou evento.
Resumindo, esse código em AMPscript é usado para:
Armazenar o nome do destinatário na variável @firstName.
Obter a data e hora atuais no fuso horário local e armazená-las na variável @localDate.
Definir uma data específica ('10/15/2018') na variável @promotionEndDate.

1.6.4. Escopo

Depois que uma variável é definida, seu escopo é definido globalmente; ou seja, pode ser referenciado posteriormente no código para exibir a saída ou usado em expressões condicionais. No entanto, as variáveis ​​também podem ser alteradas depois de terem sido definidas. Por exemplo, a data de término de uma promoção é definida em um campo em uma extensão de dados enviáveis ​​usando uma string de personalização, mas para clientes específicos, há um requisito para ajustar esse valor posteriormente no código:
%%[
var @promotionEndDate, @memberStatus
set @promotionEndDate = '10/15/2018'
set @memberStatus = status
if @memberStatus == 'gold' then
set @promotionEndDate = '11/15/2018'
endif
]%%
As variáveis ​​também podem ser definidas em si mesmas em uma função; ou seja, se a variável foi declarada anteriormente, ela pode ser usada como argumento para uma função, com base em seu valor anterior. Portanto, o código acima também pode ser expresso como:
%%[
var @promotionEndDate, @memberStatus
set @promotionEndDate = '10/15/2018'
set @memberStatus = status
if @memberStatus == 'gold' then
set @promotionEndDate = DateAdd(@promotionEndDate, 1, 'M')
endif
]%%
Além disso, uma vez que uma variável tenha sido definida, ela pode ser redefinida declarando o valor novamente. No exemplo abaixo, se a data atual for menor que (após) a data de término da associação, um null valor será definido para o status da associação.
%%[
var @membershipEndDate, @memberStatus
set @membershipEndDate = '10/15/2018'
set @memberStatus = status
if @membershipEndDate > Now() then
var @memberStatus
endif
]%%
A única exceção a esta regra de escopo é quando uma variável é usada dentro de um for bloco. Nesse cenário, a variável está bloqueada para modificação dentro do loop do processo .

1.6.5. Ordem de operações

Como outras linguagens de script, o AMPscript é interpretado de cima para baixo, o que significa que as variáveis ​​devem ser declaradas e definidas antes de serem usadas. No entanto, os componentes de e-mail são interpretados na seguinte ordem:
Pré-cabeçalho
corpo HTML
corpo do texto
Linha de assunto
Por exemplo, uma variável pode ser declarada e definida em um corpo HTML (dentro de um bloco AMPscript) e usada em uma linha de assunto:
<!--Appears in Body-->
%%[
var @subjectLine
if AttributeValue('Member Status') == 'VIP' then
set @subjectLine = 'An exclusive offer for VIP members'
else
set @subjectLine = 'A special offer for our members'
endif
]%%
<!--Appears in Subject Line-->
%%=v(@subjectLine)=%%
OBSERVAÇÃO: funções AMPscript aninhadas e variáveis ​​aninhadas não serão processadas em linhas de assunto a partir de 21 de fevereiro de 2023. Consulte este documento de ajuda para obter mais informações sobre essa alteração.

1.6.6. Usando variáveis

As variáveis ​​não são necessárias no AMPscript. É possível obter o mesmo resultado usando apenas funções, declarações condicionais e operadores. No entanto, sem variáveis:
funções e constantes precisariam ser definidas várias vezes, geralmente resultando em mais código e dificultando a manutenção
cada função AMPscript duplicada precisa ser interpretada novamente, resultando em possíveis problemas de desempenho ao enviar e-mails ou renderizar conteúdo.
O exemplo abaixo indica a inclusão de duas variáveis ​​no AMPscript para recuperar um saldo de pontos e exibir um nível de status correspondente.
%%[

var @pointsBalance, @status
set @pointsBalance = Lookup("Points Balance","Balance","MemberId", _subscriberKey)

if @pointsBalance < 100 then
set @status = "bronze"
elseif @pointsBalance > 100 and @pointsBalance < 500 then
set @status = "silver"
else
set @status = "gold"
endif

]%%

You are a valued %%=v(@status)=%% member.
Ao escrever AMPscript, é uma boa prática otimizar seu código por meio da configuração de variáveis ​​para funções comumente usadas.

1.7. Comentário

Os comentários podem ser incluídos nos blocos AMPscript. Eles estão contidos em um par de sintaxe de abertura /*e fechamento */e fornecem a capacidade de incluir uma explicação ou anotação legível para os usuários. Quaisquer comentários são ignorados pelo Marketing Cloud e não serão interpretados. Eles podem ser usados ​​em uma única linha ou percorrer várias linhas.

Exemplo 1

Este é um exemplo de comentário de uma linha:
%%[ /* Este é um exemplo de comentário de uma linha em AMPscript. */
set @variable = "valor"
]%%

Exemplo 2

Aqui está um exemplo de um comentário que atravessa várias linhas:
%%[
/*
Este é um exemplo de um comentário
que se estende por várias linhas em AMPscript.
Pode ser usado para explicar partes mais extensas
do código ou fornecer informações detalhadas.
*/

set @variable = "valor"
]%%

1.8. Function calls

As funções são interpretadas ou 'chamadas' dentro de um bloco AMPscript ou AMPscript embutido, no local onde aparecem na página ou na mensagem. No entanto, as funções não precisam estar contidas no mesmo bloco AMPscript. Por exemplo, ao usar instruções condicionais , a expressão condicional pode abranger vários blocos:
%%[

var @balance
set @balance = Lookup('Points Balance', 'Balance', 'MemberId', _subscriberKey)

]%%

%%[ if @balance < 100 then ]%%

You are a valued bronze member.

%%[ elseif @balance > 100 and @balance < 500 then ]%%

You are a valued silver member.

%%[ else ]%%

You are a valued gold member.

%%[ endif ]%%
Da mesma forma, podem (e normalmente o fazem) abranger vários blocos, conforme indicado abaixo.
<h2>Your Order Items</h2>
<ul>
%%[
var @orderId, @rows, @row, @rowCount, @i

set @orderId = AttributeValue("OrderId")
set @rows = LookupRows("Orders","OrderId", @orderId)
set @rowCount = rowcount(@rows)

if @rowCount > 0 then

for @i = 1 to @rowCount do

var @name, @value
set @row = row(@rows, @i)
set @name = field(@row,"Name")
set @value = field(@row,"Value")

]%%

<li>%%=v(@name)=%%, $%%=v(@value)=%%</li>

%%[ next @i ]%%

%%[ else ]%%

<li>No items ordered</li>

%%[ endif ]%%
</ul>

1.9. Constantes

Na programação, uma constante é um valor que nunca muda. No AMPscript, esses valores predefinidos ou codificados são usados ​​para definir um valor fixo para avaliação ou pesquisa. Eles podem ser uma constante, numérica, string ou um valor booleano.

1.9.1. Constantes numéricas

As constantes numéricas consistem em um conjunto de numerais sem aspas. Eles também podem incluir um ponto decimal e podem ser prefixados com um símbolo de menos para indicar valores negativos. Constantes numéricas não podem conter vírgulas, conforme indicado abaixo:
%%[

var @discountAmount
set @discountAmount = -10.50

]%%

1.9.2. Constantes de strings

Valores constantes de string (ou texto) devem usar aspas duplas ou simples, conforme indicado no exemplo aqui:
%%[

var @statusTier
set @statusTier = "Gold"

]%%
Se aparecerem aspas dentro do texto, as constantes de string podem escapar das aspas delimitadoras quando seu tipo de aspas for trocado (para simples ou duplo). Caracteres de aspas alternativas, como aspas inteligentes, não são suportados.
%%[

var @bonusProduct
set @bonusProduct = 'Our "Uber" Umbrella'

]%%

1.9.3. Constantes booleana

Os valores das constantes booleanas devem usar valores trueor falsee não diferenciam maiúsculas de minúsculas, conforme mostrado no exemplo abaixo:
%%[

var @statusTier, @freeShipping
set @statusTier = AttributeValue("Tier Level")

if @statusTier == "Gold" then /* string constant */
set @freeShipping = true /* Boolean constant */
endif

]%%

1.10. Atributos

e outras também podem ser usadas com AMPscript. No entanto, neste caso, os delimitadores de porcentagem dupla ( %%) não devem ser incluídos.
Se o atributo incluir um caractere de espaço ou hífen, a string deverá estar entre colchetes quando usada em uma função AMPscript.
No exemplo abaixo, uma extensão de dados enviáveis ​​inclui os campos 'MemberID', 'First Name' e 'Order-Amount':
%%[
var @MemberID, @FirstName, @OrderAmount

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.